How to Manage Credential Lifecycle and Expiration for Vultr Container Registry

Vultr Container Registry integrates with IAM, so registry access follows least-privilege policies instead of account-wide API keys. An identity with the right container.registry.* permissions can mint short-lived Docker credentials, and each set of credentials is valid only for the period the caller requests.

Follow this guide to set the expiry of minted credentials using the Vultr API, understand what happens when they expire, and renew or revoke them.

Set the Credential Expiry

Use the optional expiry_seconds parameter in the mint request to set how long the credentials remain valid, in seconds. The following example mints credentials valid for 1 hour. Replace REGISTRY_ID with your registry's ID.

$ curl "https://api.vultr.com/v2/container-registry/docker-credentials" \
    -X POST \
    -H "Authorization: Bearer ${VULTR_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
        "registry": "REGISTRY_ID",
        "expiry_seconds": 3600
    }'

The server adjusts the value you send. If you omit expiry_seconds or send a zero or negative value, the credentials expire after 86400 seconds (1 day). The server caps values above 2592000 seconds (30 days) at 30 days.

What Happens When Credentials Expire

Credentials are valid for the requested expiry_seconds, counted from the time you mint them. After that:

• The credentials fail authentication immediately. The registry denies any docker pull or docker push that uses them.
• Existing docker login sessions that rely on them stop working the next time they contact the registry.
• Vultr Container Registry does not renew or extend expired credentials. Mint a new set instead.

Re-mint Credentials

To continue after expiry, send a new mint request. The new credentials reflect the caller's IAM permissions at that moment, so any policy changes since the last mint apply automatically.

Mint fresh credentials at the start of each job or session, using the longest expiry you intend to need. Then log in with the new credentials. See How to Enable IAM Authentication for Vultr Container Registry for the login steps.

For consumers that cannot interactively re-authenticate, such as a Kubernetes cluster relying on an image pull secret, schedule a job to re-mint the credentials and update the secret before the current set expires.

Revoke Credentials Early

Expiry is the primary way credentials stop working. If you need to invalidate a set of credentials immediately, such as after a suspected leak, note that minted credentials are Harbor robot accounts, so you can manage them like other registry robots. See Robot accounts for the steps.

Revoking a credential does not change the identity's IAM policy. To stop the identity from minting new credentials, update or detach its policy as well.

Handle Credentials Securely

Treat minted credentials as secrets.

• Prefer short expiries.
• Pass credentials to docker login over stdin with --password-stdin, or store them in a secret store.
• Avoid printing credentials to logs or leaving them in shell history or environment variable dumps.
• Do not commit credentials or a creds.json file containing them to source control.