helm-external-secrets/docs/api/generator/cloudsmith.md

CloudsmithAccessToken creates a short-lived Cloudsmith access token that can be used to authenticate against Cloudsmith's container registry for pushing or pulling container images. This generator uses OIDC token exchange to authenticate with Cloudsmith using a Kubernetes service account token and generates Docker registry credentials in dockerconfigjson format.

Output Keys and Values

Key	Description
auth	Base64 encoded authentication string for Docker registry access.
expiry	Time when token expires in UNIX time (seconds since January 1, 1970 UTC).

Authentication

To use the Cloudsmith generator, you must configure OIDC authentication between your Kubernetes cluster and Cloudsmith. Your cluster must have a publicly available OIDC service account issuer endpoint for Cloudsmith to validate tokens against.

Prerequisites

1. Cloudsmith OIDC Service: Configure an OIDC service in your Cloudsmith organization that trusts your Kubernetes cluster's OIDC issuer.
2. Service Account: Create a Kubernetes service account that will be used for token exchange.
3. Proper Audiences: The service account token must include the appropriate audience for Cloudsmith (typically https://api.cloudsmith.io).

Service Account Configuration

You can determine the issuer and subject fields by creating and decoding a service account token for the service account you wish to use (this is the service account you will specify in spec.serviceAccountRef). For example, if using the default service account in the default namespace:

Obtain issuer:

kubectl create token default -n default | cut -d '.' -f 2 | sed 's/[^=]$/&==/' | base64 -d | jq -r '.iss'

Use these values when configuring the OIDC service in your Cloudsmith Workspace settings.

Configuration Parameters

Parameter	Description	Required
apiHost	The Cloudsmith API host. Defaults to api.cloudsmith.io.	No
orgSlug	The organization slug in Cloudsmith.	Yes
serviceSlug	The OIDC service slug configured in Cloudsmith.	Yes
serviceAccountRef	Reference to the Kubernetes service account for OIDC token exchange.	Yes

Example Manifest

{% include 'generator-cloudsmith.yaml' %}

Example ExternalSecret that references the Cloudsmith generator:

{% include 'generator-cloudsmith-example.yaml' %}

Using the Generated Docker Registry Secret

Once the dockerconfigjson secret is created, you can use it to authenticate with Cloudsmith's container registry in several ways:

In Pod Specifications

Reference the secret in your pod's imagePullSecrets:

apiVersion: v1
kind: Pod
metadata:
  name: my-app
spec:
  imagePullSecrets:
    - name: cloudsmith-credentials
  containers:
    - name: app
      image: docker.cloudsmith.io/my-org/my-repo/my-image:latest

In ServiceAccount

Add the secret to a ServiceAccount for automatic usage:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-service-account
imagePullSecrets:
  - name: cloudsmith-credentials

For Docker CLI Authentication

Extract the dockerconfigjson and use it with Docker:

kubectl get secret cloudsmith-credentials -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d > ~/.docker/config.json
docker pull docker.cloudsmith.io/my-org/my-repo/my-image:latest

Usage Notes

• Container Registry Access: The generated dockerconfigjson secret is specifically designed for authenticating with Cloudsmith's container registry to push or pull Docker images.
• Token Lifetime: Cloudsmith access tokens have a limited lifetime. The expiry field in the generated secret indicates when the token will expire.
• Refresh Interval: Set an appropriate refreshInterval in your ExternalSecret to ensure tokens are refreshed before expiration.
• Permissions: The generated token will have the same permissions as the OIDC service configured in Cloudsmith for container registry access.

Troubleshooting

• Token Exchange Fails: Verify that your OIDC service in Cloudsmith is correctly configured with your cluster's issuer.
• Invalid Audience: Ensure the service account token includes the correct audience for Cloudsmith API.
• Network Issues: Check that your cluster can reach the Cloudsmith API endpoint specified in apiHost.
• Container Image Pull Fails: Verify that the generated dockerconfigjson secret is properly referenced in your pod's imagePullSecrets and that the image exists in your Cloudsmith container registry.
• Registry Domain Issues: Ensure you're using the correct registry domain format (e.g., docker.cloudsmith.io/org/repo/image:tag) in your image references.
• Permissions: Confirm that your OIDC service in Cloudsmith has the necessary permissions to pull/push container images from the specific repositories.