Skip to main content

Authentication

Pulling private packages or pushing packages to an Upbound Marketplace private repository requires authentication to Upbound.

Installing private Kubernetes resources requires an image pull secret.

important

Authenticating to the Upbound Marketplace for private packages requires an Upbound account.

Prerequisites​

Install the Up command-line to generate Kubernetes secrets and to use Upbound Marketplace private resources.

Log in with the Up command-line​

Use up login to authenticate a user to the Upbound Marketplace.

up login

Configure Docker to use the up credential helper​

If you use Docker or any other OCI client, you can configure it to use Upbound credentials to interact with the Marketplace.

Install the docker-credential-up credential helper:

curl -sL "https://cli.upbound.io" | BIN=docker-credential-up sh
tip

Read the up CLI configuration documentation for more installation options.

For Docker, add up to your Docker config.json. This allows your client to use Upbound credentials to interact with the Marketplace:

{
	"credHelpers": {
		"xpkg.upbound.io": "up"
	}
}

Authenticate to push packages​

Pushing packages to the Upbound Marketplace requires a robot token. Personal API tokens and up login credentials don't work for pushing — they return a 401 error.

Create a robot token​

  1. Go to https://accounts.upbound.io/o/<your-org>/robots and create a robot account.

  2. Copy the robot's access ID and token — you can't retrieve the token again after leaving the page.

  3. Assign the robot to a team that has write permission on the target repository. See manage repository permissions for instructions.

Log in with docker​

Use docker login with the robot credentials:

docker login xpkg.upbound.io -u <robot-access-id> -p <robot-token>

You can run crossplane xpkg push to push packages to the Marketplace.

warning

If you have the docker-credential-up helper configured for xpkg.upbound.io, it may override the robot credentials. Remove or scope it if you encounter auth errors after a successful docker login.

Authenticate in CI​

In a CI pipeline, use the docker/login-action with your robot credentials stored as secrets:

- name: Log in to Upbound Marketplace
  uses: docker/login-action@v3
  with:
    registry: xpkg.upbound.io
    username: ${{ secrets.UPBOUND_ROBOT_ACCESS_ID }}
    password: ${{ secrets.UPBOUND_ROBOT_TOKEN }}

Kubernetes image pull secrets​

Packages in private repositories require a Kubernetes image pull secret. The image pull secret authenticates Kubernetes to the Upbound Marketplace, allowing Kubernetes to download and install packages.

Generating an image pull secret requires either a user account token.

important

A user account token uses your current up login profile. Logging out with up logout deactivates the token.

Use the command up controlplane pull-secret create to generate a token and Kubernetes Secret in the upbound-system namespace.

up ctp pull-secret create
WARNING: Using temporary user credentials that will expire within 30 days.
upbound-system/package-pull-secret created

Verify the secret with kubectl describe secret -n upbound-system package-pull-secret

kubectl describe secret -n upbound-system package-pull-secret
Name:         package-pull-secret
Namespace:    upbound-system
Labels:       <none>
Annotations:  <none>

Type:  kubernetes.io/dockerconfigjson

Data
====
.dockerconfigjson:  1201 bytes

Use an image pull secret​

Use an image pull secret by providing a spec.packagePullSecrets in a Configuration or Provider manifest.

Use an image pull secret by providing a spec.packagePullSecrets in a Configuration or Provider manifest.

This example installs a private Configuration named secret-configuration from the Upbound image repository using image pull secret named package-pull-secret.

apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
  name: platform-ref-aws
spec:
  package: xpkg.upbound.io/secret-org/secret-configuration:v1.2.3
  packagePullSecrets:
    - name: package-pull-secret