Applies to SUSE Private Registry

8 How do I automate access to a proxy-cache project? #

A proxy-cache project in SUSE Private Registry retrieves container images and Open Container Initiative (OCI) Helm charts from SUSE Application Collection on demand. A SUSE Application Collection service account authenticates upstream requests, while a SUSE Private Registry robot account authenticates downstream clients. This separation lets administrators retain upstream credentials in the registry and give automation project-scoped access through command-line tools or Terraform.

8.1 What do I need before configuring the proxy? #

A running SUSE Private Registry instance and system administrator access to configure registry endpoints and projects.
Project administrator access to create a project robot account.
A SUSE Application Collection organization administrator who can create a service account, with subscriptions covering the artifacts you need.
Network access from SUSE Private Registry to SUSE Application Collection, including its authentication and artifact download services.
Trusted Transport Layer Security (TLS) certificates and working Domain Name System (DNS) resolution for both registries.
Docker and Helm clients for testing pulls.
Terraform and cluster credentials if you follow the infrastructure-as-code examples.

Project robot accounts act within one project. System robot accounts can have system permissions and permissions across selected projects. Robot accounts authenticate OCI clients and application programming interface (API) requests, not interactive web sessions. A SUSE Application Collection service account belongs to one organization and inherits that organization’s subscriptions.

8.2 How do I find available components? #

Use the upstream collection to discover applications, container images and Helm charts. A proxy-cache project does not automatically list or download the upstream collection. Its repository list contains artifacts cached after clients request them.

Browsing the collection #

Open the SUSE Application Collection applications page.
Filter by container images or Helm charts, or search for an application.
Open the application and select an artifact version.
Figure 8.1: Application Collection artifact details and available versions #
Record its repository path and tag from the artifact details or pull command. For example, container paths start with containers/ and chart paths start with charts/.
Check that your service account’s organization has the subscription required to pull the selected artifact.

Collection visibility does not grant download access. For an example of viewing an application and its available artifact versions, see the SUSE Application Collection documentation on reviewing application details. For programmatic discovery, see the Metadata Service API. Follow each endpoint’s pagination and filtering rules rather than treating one response as the complete collection.

8.3 How do I create upstream credentials? #

Create a SUSE Application Collection service account for registry-to-registry access. Keep its credentials separate from the SUSE Private Registry robot credentials distributed to clients.

Creating a service account #

Sign in to SUSE Application Collection with an organization administrator account.
Open your profile menu and select Settings.
Select Service accounts.
Enter a description and select the organization that provides the required subscriptions.
Click Create.
Save the generated username and secret in your approved secret store.

For account requirements, see the SUSE Application Collection authentication documentation.

8.4 How do I configure the registry endpoint and proxy project? #

Register SUSE Application Collection as an upstream Docker Registry endpoint, then select that endpoint in a new proxy-cache project.

Configuring the proxy #

Sign in to SUSE Private Registry as a system administrator.
Go to Registries and click New endpoint.

Configure the endpoint with the following values:

Field	Value
Provider	Docker Registry
Name	`application-collection`
Endpoint URL	`https://dp.apps.rancher.io`
Access ID	The SUSE Application Collection service account username
Access Secret	The SUSE Application Collection service account secret
Verify Remote Cert	Enabled

Harbor registry endpoint form for Application Collection

Figure 8.2: Application Collection registry endpoint form in Harbor #

Click Test Connection and resolve authentication or connectivity errors before continuing.
Click OK to save the endpoint.
Go to Projects and click New Project.
Set Project Name to application-collection and keep the project private.
Enable Proxy Cache and select the application-collection registry endpoint.
Click OK.

Warning

Clients with pull access to this project can request upstream artifacts accessible to the configured SUSE Application Collection service account. Restrict project membership and robot permissions to authorized consumers.

Proxy-cache projects do not accept pushes. The first pull of an uncached artifact requires upstream connectivity. Review the project’s retention policy because cached artifacts can expire. Proxy caching does not replace a complete mirror for an air-gapped environment.

For upstream configuration details, see Mirror with Harbor.

8.5 How do I create a pull-only robot account? #

Use a project robot account for clients that only consume artifacts from the proxy. Do not grant registry administration permissions to this account.

Creating a pull-only account #

Open Projects, select application-collection and select Robot Accounts.
Click New Robot Account.
Enter a name, such as proxy-reader, and a description.
Set an expiration time that matches your credential rotation policy.
Continue to the permissions step and select only Pull Repository.
Click FINISH.
Use Export to File or the copy control to save the generated credentials securely.

Use the full generated username, including the configured prefix and project name. With the configured robot@ prefix, an example is robot@application-collection+proxy-reader. The secret is not retrievable after creation; refresh it if you lose it.

8.6 How do I replace the dollar sign in robot user names? #

If a client or automation system has trouble with the default robot$ prefix, a system administrator can change the robot name prefix to robot@. The configured prefix applies to existing and new system and project robot accounts. Robot accounts created with Harbor 2.1 or earlier keep the robot$ prefix.

Changing the robot name prefix #

Sign in to SUSE Private Registry as a system administrator.
Go to Configuration and select System Settings.
Find Robot Name Prefix and replace robot$ with robot@.
Save the change.
Update stored robot user names in Docker and Helm clients, Terraform variables, automation systems and Kubernetes image-pull secrets.
Test authentication with the updated username before removing the old client configuration.

The account name and secret do not change when you update the prefix. For example, robot$application-collection+proxy-reader becomes robot@application-collection+proxy-reader. The change is global, so coordinate it with every team and automation system that uses robot accounts.

SUSE Private Registry Configuration page showing the Robot Name Prefix field

Figure 8.3: Robot Name Prefix setting in SUSE Private Registry #

For more information, see Configure Robot Account Prefix.

8.7 How do I pull images and charts through the proxy? #

Replace the upstream host with your registry host and proxy project, while preserving the artifact repository path. For example, dp.apps.rancher.io/containers/IMAGE:TAG becomes REGISTRY_HOST/application-collection/containers/IMAGE:TAG.

Authenticating and pulling artifacts #

In Bash, enter the registry host and the pull-only robot credentials:
```
printf '%s' "$ROBOT_SECRET" | docker login "$REGISTRY_HOST" \
  --username "$ROBOT_USERNAME" --password-stdin
printf '%s' "$ROBOT_SECRET" | helm registry login "$REGISTRY_HOST" \
  --username "$ROBOT_USERNAME" --password-stdin
unset ROBOT_SECRET
```
Use a trusted certificate rather than disabling TLS verification. Client login stores credentials locally; protect the client credential files or use a credential helper. For more SUSE Application Collection Docker, Helm and Kubernetes authentication examples, see the authentication documentation.

Enter the image name and tag selected from the collection, then pull through the proxy:

read -r -p 'Container name, without containers/: ' IMAGE_NAME
read -r -p 'Container tag: ' IMAGE_TAG
docker pull "$REGISTRY_HOST/application-collection/containers/$IMAGE_NAME:$IMAGE_TAG"

Enter the chart name and version selected from the collection, then pull the chart:

read -r -p 'Chart name, without charts/: ' CHART_NAME
read -r -p 'Chart version: ' CHART_VERSION
helm pull "oci://$REGISTRY_HOST/application-collection/charts/$CHART_NAME" \
  --version "$CHART_VERSION"

Open the project’s Repositories view and confirm that the requested artifacts appear.

Important

Downloading a chart through the proxy does not rewrite the container image references inside that chart. Configure chart-specific registry values and namespace-local image-pull secrets before deploying its workloads.

8.8 How do I manage registry resources with infrastructure as code? #

The goharbor/harbor Terraform provider authenticates to the SUSE Private Registry API with a robot username and secret. Use a separate management robot, not the pull-only account distributed to workloads. The following example manages the upstream registry endpoint and proxy-cache project configured in Section 8.4, “How do I configure the registry endpoint and proxy project?”. The endpoint must point directly to SUSE Application Collection so SUSE Private Registry can retrieve artifacts to cache. Clients still pull artifacts through the proxy-cache project, not directly from SUSE Application Collection.

The example pins provider version 3.12.5 and requires Terraform 1.14.0 or later. For Terraform language and command-line guidance, see the Terraform documentation. The upstream provider lists Harbor 2.15 in its compatibility tests; this does not establish SUSE certification of the provider.

Warning

In Terraform, setting sensitive = true hides values in normal output but does not encrypt them or exclude resource secrets from state. The endpoint’s access_secret and ordinary Kubernetes Secret data remain in Terraform state. Use encrypted, access-restricted state storage and protect saved plans, backups and automation logs. Do not commit credentials, state files or secret-bearing variable files.

Preparing the management account #

As a system administrator, go to Administration › Robot Accounts and click New Robot Account.
Enter an account name, such as terraform-registry, a description and an expiration time.
Grant the system permissions required by the following table.
Associate the account with the existing application-collection project and grant the listed project permissions. Do not enable Cover all projects for this example.
Click FINISH and save the full username and secret securely.

Scope	Permission	Purpose in this example
System	List Project	Look up the project by name with `data.harbor_project`.
System	Read Registry	Read the imported registry endpoint.
System	Update Registry	Update endpoint settings or upstream credentials.
Project	Read Scanner	Read the project’s scanner during the data-source lookup.
Project	Read Project	Read the imported project’s settings.
Project	Update Project	Apply changes to project settings.

These permissions follow the provider’s API calls for this example. Additional resources can require different permissions; Pull Repository alone does not grant registry management access. Configuration-related APIs are not generally available to robot accounts. This example leaves scanner assignment and storage quota management to the administrator.

Configuring the provider #

In a dedicated Terraform working directory, create main.tf with the following configuration:

terraform {
  required_version = ">= 1.14.0"

  required_providers {
    harbor = {
      source  = "goharbor/harbor"
      version = "3.12.5"
    }
  }
}

provider "harbor" {
  insecure = false
}

data "harbor_project" "application_collection" {
  name = "application-collection"
}

output "proxy_project_id" {
  value = data.harbor_project.application_collection.project_id
}

Set the registry URL and management credentials in Bash:
```
read -r -p 'Private Registry URL, including https://: ' HARBOR_URL
read -r -p 'Full management robot username: ' HARBOR_USERNAME
read -r -s -p 'Management robot secret: ' HARBOR_PASSWORD
printf '\n'
export HARBOR_URL HARBOR_USERNAME HARBOR_PASSWORD
unset HARBOR_SESSION_ID HARBOR_BEARER_TOKEN
terraform init
terraform validate
terraform plan
```
HARBOR_URL is the registry’s base URL, without /api/v2.0. Explicit insecure = false enables certificate verification despite the provider’s default. Supply a trusted certificate authority for privately signed certificates. In automation, inject credentials from your protected secret store instead of using interactive input.
Confirm that the plan reads the intended project before adding managed resources.

Adopting the endpoint and project #

Add the following configuration to main.tf:

variable "collection_username" {
  type = string
}

variable "collection_secret" {
  type      = string
  sensitive = true
}

resource "harbor_registry" "application_collection" {
  name          = "application-collection"
  provider_name = "docker-registry"
  endpoint_url  = "https://dp.apps.rancher.io"
  access_id     = var.collection_username
  access_secret = var.collection_secret
  insecure      = false

  lifecycle {
    prevent_destroy = true
  }
}

resource "harbor_project" "application_collection" {
  name        = "application-collection"
  public      = false
  registry_id = harbor_registry.application_collection.registry_id

  lifecycle {
    prevent_destroy = true
  }
}

The numeric registry_id enables proxy caching. The access_id and access_secret are upstream SUSE Application Collection credentials, not the management robot credentials.

Enter the upstream credentials and the existing resource IDs:

read -r -p 'Application Collection service account username: ' TF_VAR_collection_username
read -r -s -p 'Application Collection service account secret: ' TF_VAR_collection_secret
printf '\n'
export TF_VAR_collection_username TF_VAR_collection_secret
read -r -p 'Existing registry endpoint ID: ' ENDPOINT_ID
read -r -p 'Existing proxy project ID: ' PROJECT_ID
terraform import harbor_registry.application_collection "/registries/$ENDPOINT_ID"
terraform import harbor_project.application_collection "/projects/$PROJECT_ID"
terraform plan

Use the numeric IDs from the SUSE Private Registry API. Import existing resources before applying; otherwise Terraform attempts to create resources with names that already exist.

Review differences against the existing project settings. Match settings you need to preserve, including scanning and content-trust policies, before applying.
Run terraform apply only after reviewing the plan in an isolated test environment.
Remove credentials from the shell environment when finished:
```
unset HARBOR_PASSWORD TF_VAR_collection_secret
```

Creating a new endpoint requires Create Registry; creating a new project requires Create Project. A system administrator must arrange the management robot’s project permissions for subsequent reads and updates of a new project. Do not assume that project creation grants those permissions automatically. Use an administrator-assisted setup when the new project cannot yet be associated with the robot. Deletion requires additional permissions; the example blocks destruction with prevent_destroy and does not enable force_destroy.

For resource schemas, see the Harbor provider documentation.

8.9 How do I deploy workloads through the proxy with infrastructure as code? #

Use the pull-only robot account for both chart downloads and container image pulls. The registry credentials in the Helm provider authenticate chart downloads; a namespace-local image-pull secret authenticates the workload images. Your kubeconfig authenticates Terraform to the cluster separately and needs permission to manage the deployment resources.

This example uses the SUSE Application Collection etcd chart and its global.imageRegistry and global.imagePullSecrets values. Confirm these values in the selected chart version before applying. Other charts can use different value names. The providers are pinned to hashicorp/helm 3.3.0 and hashicorp/kubernetes 3.3.0.

Deploying a chart #

Create a separate Terraform working directory and a main.tf file with the following configuration:

terraform {
  required_version = ">= 1.14.0"

  required_providers {
    helm = {
      source  = "hashicorp/helm"
      version = "3.3.0"
    }
    kubernetes = {
      source  = "hashicorp/kubernetes"
      version = "3.3.0"
    }
  }
}

variable "registry_host" {
  type = string
}

variable "robot_username" {
  type = string
}

variable "robot_secret" {
  type      = string
  sensitive = true
}

variable "chart_version" {
  type = string
}

variable "kubeconfig_path" {
  type    = string
  default = "~/.kube/config"
}

provider "kubernetes" {
  config_path = pathexpand(var.kubeconfig_path)
}

provider "helm" {
  kubernetes = {
    config_path = pathexpand(var.kubeconfig_path)
  }

  registries = [
    {
      url      = "oci://${var.registry_host}"
      username = var.robot_username
      password = var.robot_secret
    }
  ]
}

resource "kubernetes_namespace_v1" "application_collection" {
  metadata {
    name = "application-collection"
  }
}

resource "kubernetes_secret_v1" "proxy_pull" {
  metadata {
    name      = "proxy-pull"
    namespace = kubernetes_namespace_v1.application_collection.metadata[0].name
  }

  type = "kubernetes.io/dockerconfigjson"

  data = {
    ".dockerconfigjson" = jsonencode({
      auths = {
        (var.registry_host) = {
          username = var.robot_username
          password = var.robot_secret
          auth     = base64encode("${var.robot_username}:${var.robot_secret}")
        }
      }
    })
  }
}

resource "helm_release" "etcd" {
  name       = "collection-etcd"
  namespace  = kubernetes_namespace_v1.application_collection.metadata[0].name
  repository = "oci://${var.registry_host}/application-collection/charts"
  chart      = "etcd"
  version    = var.chart_version

  values = [yamlencode({
    global = {
      imageRegistry    = "${var.registry_host}/application-collection"
      imagePullSecrets = [kubernetes_secret_v1.proxy_pull.metadata[0].name]
    }
  })]
}

Set registry_host to the host name and optional port, without a scheme or project path. The Secret uses that host as its authentication key. The provider encodes the data values for Kubernetes; do not base64-encode the complete JSON value again. The release references the Secret, ensuring that Terraform creates the Secret before installing the chart.

In Bash, enter your pull-only robot credentials and the chart version selected from the collection:

read -r -p 'Private Registry host, without https://: ' TF_VAR_registry_host
read -r -p 'Full pull-only robot username: ' TF_VAR_robot_username
read -r -s -p 'Pull-only robot secret: ' TF_VAR_robot_secret
printf '\n'
read -r -p 'Application Collection etcd chart version: ' TF_VAR_chart_version
export TF_VAR_registry_host TF_VAR_robot_username TF_VAR_robot_secret TF_VAR_chart_version
terraform init
terraform validate
terraform plan

Confirm the kubeconfig context targets your test cluster and review the planned resources.
If the application-collection namespace already exists, import it into Terraform state before applying:
```
terraform import kubernetes_namespace_v1.application_collection application-collection
```
Run terraform apply in the test environment.

Check the workload with your configured kubeconfig:

kubectl --kubeconfig "$HOME/.kube/config" -n application-collection get pods
kubectl --kubeconfig "$HOME/.kube/config" -n application-collection get pods \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\n"}{.spec.containers[*].image}{"\n"}{.spec.imagePullSecrets[*].name}{"\n"}{end}'
unset TF_VAR_robot_secret

If you set kubeconfig_path, use that same path for kubectl. Confirm that container image paths include your registry and proxy project and that Pods reference proxy-pull. Investigate ImagePullBackOff events before treating the deployment as verified.

Run terraform plan again and check for unexpected changes.

The Secret’s ordinary data attribute stores credentials in state even though robot_secret is sensitive. The providers offer additional secret-handling options; evaluate their version requirements before changing this example. For schemas, see the Helm provider and Kubernetes Secret resource documentation.

8.10 How do I rotate credentials and troubleshoot access? #

To refresh a robot secret, select the account under Robot Accounts and choose Action › Refresh Secret. Store the new secret and update client credentials, automation secrets and Kubernetes image-pull secrets. For Terraform, update protected HARBOR_PASSWORD or TF_VAR_robot_secret values for the corresponding account. Apply the workload configuration to update the image-pull secret after rotation. Do not rotate the management credential during an active Terraform run. Test a new pull before retiring the previous configuration. Deactivate or delete accounts that no longer need access. Rotate upstream service-account credentials separately and update the registry endpoint when they change.

For a downstream 401 or 403 response, check the full robot username, secret, expiration, enabled status and project permissions.
For upstream authentication failures, check the endpoint credentials and the service account’s organization subscriptions.
For missing repositories in a new project, pull an artifact first; the project is not an upstream collection browser.
For a missing tag, confirm the selected version in the upstream collection.
For TLS or connection failures, check certificate trust, DNS resolution and network access from the registry.
For upstream 429 responses, review SUSE Application Collection rate limits and reduce concurrent requests.
For Terraform API 403 responses, check the management robot’s permissions for each provider API call.
For Kubernetes authorization failures, check kubeconfig credentials and role-based access control (RBAC), not the registry robot credentials.

For account permissions and cache behavior, see the upstream documentation: