Pulp OCI token configuration
Pulp’s OCI registry uses token authentication by default. A registry client
gets a 401 with a Bearer realm=... challenge, asks the realm for a signed
token, and retries with it. pulp_container 2.28.1 signs those tokens with an
asymmetric key pair and needs four settings for it. SHC fills all four, so the
registry works on a fresh install with no operator input:
| SHC variable | Pulp environment setting | Blank means |
|---|---|---|
oci.tokenServer | PULP_TOKEN_SERVER | <contentOrigin>/token/, and contentOrigin itself defaults to https://<pulp-web host> |
oci.signatureAlgorithm | PULP_TOKEN_SIGNATURE_ALGORITHM | ES256 |
oci.privateKeyPath | PULP_PRIVATE_KEY_PATH | /etc/pulp/certs/oci-token.key |
oci.publicKeyPath | PULP_PUBLIC_KEY_PATH | /etc/pulp/certs/oci-token.pub |
All four ship blank in vars.yaml and compose.yaml applies the fallbacks, so an
estate only sets one to override it. Nonempty values are forwarded as given,
with no URL normalization or algorithm allowlist. Quotes and dollar signs
survive YAML rendering and Compose interpolation as literal values.
If any of the four is missing, pulp_container raises while it builds the 401
challenge, and every anonymous /v2/, /v2/_catalog and /token/ request
returns 500 instead (SHC-732). pulpcore-manager check --deploy reports the
missing settings as pulp_container.E001.
The key pair
Section titled “The key pair”The pulp-keygen start job generates the pair on the pulp-certs volume, the
same way it already creates database_fields.symmetric.key. It runs as root
before pulp-migration and does this when the algorithm is ES256:
- no private key at
oci.privateKeyPath: generate a prime256v1 key underumask 077, owned by the pulp uid 700 with mode 0600, and drop any stale public key next to it - no public key at
oci.publicKeyPath: derive it from the private key, owned by 700 with mode 0644 - both present: change nothing
An existing private key is never overwritten, and the key material is never
printed. Any other algorithm means the operator supplies the pair: point
oci.privateKeyPath and oci.publicKeyPath at files inside the Pulp
container, and pulp-keygen leaves them alone. A key path that cannot be
written fails the start job and with it the install or update, rather than
starting Pulp with a registry that 500s.
The pair lives on pulp-certs, so it rides the regular volume snapshot in a
shc backup create of the stack. Never reuse the database encryption key or
the APT signing material for OCI tokens.
Rotation
Section titled “Rotation”Delete both files and run an update, which runs every start job again:
d=/var/lib/shc/deployments/<tenant>/<stack>/<env>/mounts/pulp-certssudo rm "$d/oci-token.key" "$d/oci-token.pub"sudo shc -t <tenant> -e <env> update <stack>pulp_container reads both files on every request, so the new pair takes effect
as soon as pulp-keygen writes it. Every token signed with the old key stops
verifying at that moment. Registry clients re-authenticate on their next 401,
so a pull or push in flight can fail once and should be retried.
Checking a deployment
Section titled “Checking a deployment”After an install or update, from outside the estate:
curl -si https://artifacts.bitspur.com/v2/This must return 401 with a registry API version header and:
WWW-Authenticate: Bearer realm="https://artifacts.bitspur.com/token/",service="artifacts.bitspur.com"The realm comes from contentOrigin, and the service is the host the client
asked for. A deployment that answers on several hosts shares one realm, and the
token’s audience is still the host the client used.
An anonymous token for a public distribution proves signing works:
curl -s 'https://artifacts.bitspur.com/token/?service=artifacts.bitspur.com&scope=repository:<name>:pull'It returns JSON with a token whose access entry lists pull when the
distribution is public. For a private distribution the anonymous token’s
actions list is empty, and the registry refuses the pull. Inside the stack,
pulpcore-manager check --deploy no longer lists pulp_container.E001.
Publishing an image
Section titled “Publishing an image”Push with a Pulp user that holds the container namespace and distribution
roles for the target. The admin can push anywhere; a narrower user needs its
roles granted in Pulp first. No /v2/ or /pulp/content/ prefix belongs in
the image name:
docker login artifacts.bitspur.comdocker push artifacts.bitspur.com/<namespace>/<name>:<tag>The first push creates the namespace, repository and distribution. Pulp’s
new-distribution default is private=False, so check the result and flip
private if the image must not be anonymously pullable. Record the manifest
digest after the push and verify an immutable pull by digest.
Focused regression checks
Section titled “Focused regression checks”Run the catalog tests from the repository root:
GOMAXPROCS=2 go test -C tests -mod=readonly ./unit/catalog -run TestPulpOCI -count=1TestPulpOCITokenKeygen runs the rendered pulp-keygen command against a
temporary directory with real openssl and a stub chown, and checks the pair
is P-256, matched, correctly moded and never regenerated over an existing key.
Set SHC_TEST_COMPOSE_SCALARS=1 to include the real Compose scalar round trip,
which runs isolated, networkless probe containers from the locally available
pinned Pulp image without pulling.
apps/standalone/pulp/tests/token_config_regression.py checks the installed
2.28.1 challenge and deployment-check function bodies in the pinned image. It
verifies the version and source hashes, then executes only the extracted
definitions with controlled settings.