ec2-api — Interactions

Interactions — ec2-api — branch 17.0.0

Branch 17.0.0 @ 32740781f605 — repository https://opendev.org/openstack/ec2-api (retired; local branch pre-retirement) — analysed on 2026-10-29

Other repositories cited: keystone: = openstack/keystone stable/2026.2 @ e6dc5ae07 (the OpenKeel target, not the Keystone ec2-api 17.0.0 was released with); keystoneclient: = python-keystoneclient stable/2026.2 @ b76de6a3; novaclient: / neutronclient: = local clones used only for exception attributes.

ec2-api uses no message bus (no oslo.messaging import anywhere in ec2api/), no Redis, and no notifications. It talks to its own database, to Keystone, Nova, Neutron, Cinder and Glance over REST, to an S3 endpoint (image bundles), to Nova's metadata service, to an oslo.cache back end (metadata), and runs openssl.

1. Database

1.1 Schema

Migrations: one sqlalchemy-migrate script, ec2api/db/sqlalchemy/migrate_repo/versions/001_juno.py:20 (no Alembic). Models: ec2api/db/sqlalchemy/models.py:41. The migrated SQLite schema is _rewrite/schema-sqlite-migrated_17.0.0.sql, the model DDL _rewrite/schema-mysql_17.0.0.sql; they are identical apart from the migrate_version bookkeeping table and the MySQL table options (_rewrite/schema-diff_17.0.0.md).

MySQL: ENGINE=InnoDB, CHARSET=utf8 (utf8mb3) on both tables, and the database default charset is altered to utf8 (ec2api/db/sqlalchemy/migrate_repo/versions/001_juno.py:48). With the default utf8_general_ci collation, id, os_id and the LIKE queries below are case-insensitive.

1.2 The item model

_pack_item_data / _unpack_item_data (ec2api/db/sqlalchemy/api.py:319): the Python dict of an item is stored as os_id and vpc_id columns plus data = json.dumps(rest) (Python's default separators ", " and ": "), id excluded. Reading merges them back. The kind is **the prefix of id**; queries by kind use id LIKE '<kind>-%'.

Not stored: key pairs (Nova, by name), availability zones, reservations (r- IDs are a field of instances), and the derived IDs rtbassoc-, eipassoc-, eni-attach- (§ 07 algorithm 1).

1.3 Queries (reconstructed SQL)

All queries go through model_query without soft-delete filtering (ec2api/db/sqlalchemy/api.py:80). Each function runs in autocommit mode: no transaction spans an action; consistency relies on OnCrashCleaner compensations (ec2api/api/common.py:41).

Every function requires a user or admin context (ec2api/db/sqlalchemy/api.py:67, ec2api/context.py:128). The admin context has project_id = None (ec2api/context.py:140), so project-filtered queries return nothing for it; the metadata service sets the instance's project on its admin context first (ec2api/metadata/__init__.py:272).

Describe operations are the heaviest users: DescribeInstances reads instances, ENIs (with their own describe: addresses, ports, security groups), volumes, images and public images, tags (ec2api/api/instance.py:325); see _rewrite/action-translation_17.0.0.md for observed counts.

1.4 Locking and concurrency

• The only lock is the oslo.concurrency external (file) lock around default-VPC creation, ec2api-default-vpc-lock-<project>- (ec2api/api/vpc.py:37, ec2api/api/vpc.py:175). It serialises processes on one host sharing lock_path; replicas on several hosts can each create a default VPC.
• No SELECT … FOR UPDATE, no optimistic versioning: two concurrent modifications of the same item (a route table, a VPN connection's cidrs) are last-writer-wins [inferred].
• Item IDs are random (random.randint(1, 0xffffffff), Mersenne Twister, ec2api/db/sqlalchemy/api.py:91); a collision is not retried.

2. Keystone

2.1 POST /v3/ec2tokens (every request)

Frame sent by ec2-api for a SigV4 request (shape from ec2api/api/__init__.py:190; values illustrative):

POST /v3/ec2tokens HTTP/1.1
Content-Type: application/json

{"ec2Credentials": {
  "access": "a1b2c3…",
  "signature": "5d672d79c15b13162d9279b0855cfba6789a8edb4c82c400e06b5924a6f2b5d7",
  "host": "ec2.example.org:8788",
  "verb": "POST",
  "path": "/",
  "params": {},
  "headers": {"Host": "ec2.example.org:8788", "X-Amz-Date": "20230622T101500Z",
              "Authorization": "AWS4-HMAC-SHA256 Credential=a1b2c3…/20230622/RegionOne/ec2/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=5d67…",
              "Content-Type": "application/x-www-form-urlencoded; charset=utf-8", "Content-Length": "43", "User-Agent": "Boto3/…"},
  "body_hash": "<sha256 hex of 'Action=DescribeInstances&Version=2016-11-15'>"}}

For SigV2, params holds every request parameter except Signature (AWSAccessKeyId, SignatureMethod, SignatureVersion=2, Timestamp, Action, Version, …). Keystone answers 200 with X-Subject-Token and a v3 token body (keystone:keystone/api/ec2tokens.py:76); ec2-api reads it with keystoneclient.access.AccessInfo.factory (ec2api/api/__init__.py:219). Errors: 401 (bad or missing signature, expired), 404 (unknown access key, keystone:keystone/api/_shared/EC2_S3_Resource.py:71), 503 when ec2credential is not enabled. No timeout, no retry, no caching.

2.2 Service catalogue and service credentials

• All OpenStack calls use the session built from the user's token (ec2api/api/__init__.py:229): endpoints come from the catalogue in the token (public interface by default [inferred: keystoneauth default]).
• The admin session ([keystone_authtoken] auth plugin and session options, ec2api/clients.py:44, ec2api/clients.py:145) is a process-wide singleton used for: Nova servers.list(all_tenants=True, project_id=…) and servers.get in DescribeInstances, DescribeVolumes, DescribeInstanceAttribute, _is_ebs_instance, instance auto-creation (ec2api/api/instance.py:342, ec2api/api/instance.py:494, ec2api/api/instance.py:1126, ec2api/api/instance.py:1472, ec2api/api/volume.py:165); everything in the metadata service (ec2api/metadata/__init__.py:267). The service user therefore needs Nova's admin rules for all_tenants listing and the extended attributes (OS-EXT-SRV-ATTR:*).
• keystone.ec2.list(user_id) (keystoneclient v3 /v3/users/{id}/credentials/OS-EC2) with the user's token, to sign S3 calls with the user's first EC2 credential (ec2api/api/image.py:1072).

3. Nova

Version negotiation (ec2api/clients.py:102), once per process: GET the compute endpoint's version document; if the current version is v2.1, use microversion 2.32 when supported, else the maximum supported; a non-2.1 endpoint uses legacy 2. 2.3 brings the OS-EXT-SRV-ATTR fields, 2.10 the user_id keypair lookup, 2.32 BDM tags (ec2api/clients.py:52).

4. Neutron

tenant_id=<project> filters are passed on most list calls; Neutron error classes are mapped to EC2 codes at the call sites listed in 02 § 3.1.

5. Cinder and Glance

• Cinder (ec2api/clients.py:86): the API version is deduced from the endpoint URL (get_volume_api_from_url). Calls: volumes.create(size, snapshot_id, volume_type, availability_zone), volume.update(display_name), volumes.get/list/delete, volume_snapshots.create(volume_id, force=True), snapshot.update(display_name, display_description), volume_snapshots.get/list/delete.
• Glance v2 (ec2api/clients.py:81): images.list(), images.get, images.create(**properties), images.upload(id, data, image_size), images.image_import(id, method='web-download', uri), images.update(id, visibility | image_state), images.delete. Image properties written by ec2-api: name, image_location, root_device_name, bdm_v2, block_device_mapping (JSON string), mappings (S3 manifests), architecture, kernel_id, ramdisk_id, image_state, ec2_id (Nova createImage metadata) (ec2api/api/image.py:221, ec2api/api/image.py:155).

6. S3 (image bundles)

_s3_conn (ec2api/api/image.py:1070): botocore S3 client on s3_url, region s3_region, signature s3v4, keys = access/secret of the first EC2 credential Keystone lists for the user. get_object(Bucket, Key) for the manifest and each part (ec2api/api/image.py:863, ec2api/api/image.py:1013). ClientErrors become EC2 errors (ec2api/api/__init__.py:377).

7. Metadata service exchanges

• Inbound from the Neutron metadata agent: GET /latest/meta-data/… with X-Instance-ID, X-Tenant-ID, X-Forwarded-For, X-Instance-ID-Signature (ec2api/metadata/__init__.py:202).
• Outbound to Nova metadata for /openstack/…: the same path and query, headers X-Forwarded-For, X-Instance-ID, X-Tenant-ID, X-Instance-ID-Signature (recomputed), optional client certificate (ec2api/metadata/__init__.py:173).
• Cache: GET/SET ec2api-metadata-<instance uuid> holding {metadata, owner_id}, expiration cache_expiration (ec2api/metadata/api.py:102). Without [cache] enabled, a warning is logged and every request rebuilds the metadata (one DescribeInstances plus Nova calls) (ec2api/metadata/__init__.py:83).

8. Local processes and files

• openssl enc -d -aes-128-cbc -in <file> -K <key> -iv <iv> -out <file> (ec2api/api/image.py:1037); key and IV decrypted with the RSA private key x509_root_private_key (PKCS#1 v1.5, ec2api/api/image.py:1091). The key appears on the command line of the child process.
• Temporary directories under image_decryption_dir (default /tmp) for S3 imports (ec2api/api/image.py:891); bucket directories under buckets_path (ec2api/s3/s3server.py:52).

Source: reverse-spec-ec2-api/03-interactions_17.0.0.md. The _rewrite/ and _inventory/ files are not published on the site.