Skip to content
SHC Docs

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 variablePulp environment settingBlank means
oci.tokenServerPULP_TOKEN_SERVER<contentOrigin>/token/, and contentOrigin itself defaults to https://<pulp-web host>
oci.signatureAlgorithmPULP_TOKEN_SIGNATURE_ALGORITHMES256
oci.privateKeyPathPULP_PRIVATE_KEY_PATH/etc/pulp/certs/oci-token.key
oci.publicKeyPathPULP_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 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 under umask 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.

Delete both files and run an update, which runs every start job again:

Terminal window
d=/var/lib/shc/deployments/<tenant>/<stack>/<env>/mounts/pulp-certs
sudo 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.

After an install or update, from outside the estate:

Terminal window
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:

Terminal window
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.

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:

Terminal window
docker login artifacts.bitspur.com
docker 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.

Run the catalog tests from the repository root:

Terminal window
GOMAXPROCS=2 go test -C tests -mod=readonly ./unit/catalog -run TestPulpOCI -count=1

TestPulpOCITokenKeygen 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.