Fuzzball Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

Using Secrets in Workflows

After your secrets have been created, you can reference them when building your workflows in the Fuzzball web UI or within a Fuzzfile to access containers in a private container registry or data within a private S3 bucket.

Please select either the web UI or CLI tab to see the appropriate instructions for your environment.

You can configure a secret to access an S3 bucket by first configuring a volume for your workflow. The image below has configured an ephemeral volume with the reference data for the workflow. Clicking ADD INGRESS brings up a dialog where you can configure data ingress for your workflow.

Volume ready for ingress configuration

The image below has set up an ingress configuration which reads from Source URI s3://my-bucket and stages the data at the root of the volume as Destination URI file://my-input.tgz. The Secret drop down lists only the secrets that can be used for the source you chose – here, only S3 secrets – and my-user-s3-secret is selected. Timeout is optional. You can save this configuration by clicking DONE at the bottom right of the dialog.

File ingress configuration

The saved ingress now appears under Ingress (Before Jobs Run) as s3://my-bucket -> file://my-input.tgz, and you can return to editing the remainder of your workflow.

Volume with its S3 ingress saved

You can also configure a secret to access a container in a private registry by first selecting a job’s configuration to edit. In the image below, we have selected job hello to edit.

Editing job hello

You can specify your container from a private registry and the secret to access it by navigating to the Environment tab of your job and entering the full image reference – registry, container name, and tag – in the single Image URI field. You can configure the secret to access this container with the Image pull secret drop down, which lists only the OCI Image secrets visible to your account; leave it empty for public images. Once Image URI is set, the drop down narrows further to image secrets whose trusted domains match that URI’s registry hostname – the same rule Fuzzball applies at submit time. In the image below, the container at URI docker://privaterepo/alpine-extra:latest is pulled using OCI secret my-oci-secret.

Set OCI secret

If you open an existing workflow draft that used the unsupported image.secrets (plural map) field, the web UI converts the first entry to the singular image.secret field and discards the rest. Confirm that the workflow names the image pull secret you intended.

Inside of the YAML workflow specification, secrets are referenced via a URI of the form secret://<scope>/<secret name> where scope is user, group, organization, or cluster. The account scope is also accepted as a legacy alias for group. For instance, consider the following for an S3 secret called my-user-s3-secret with user scope:

[snip...]
    ingress:
      - source:
          uri: s3://my-bucket/my-input.tgz
          secret: secret://user/my-user-s3-secret
        destination:
          uri: file://my-input.tgz

A secret with the group scope requires the following change to the URI reference.

[snip...]
    ingress:
      - source:
          uri: s3://my-bucket/my-input.tgz
          secret: secret://group/my-user-s3-secret
        destination:
          uri: file://my-input.tgz

For an image registry secret for a user:

[snip...]
    image:
      uri: docker://privaterepo/alpine-extra:latest
      secret: secret://user/my-oci-secret

For an image registry secret for a group:

[snip...]
    image:
      uri: docker://privaterepo/alpine-extra:latest
      secret: secret://group/my-oci-secret

Complete details of secret usage with various storage locations and OCI registries can be found in the Fuzzfile Syntax Guide.

Field name requirements

The correct field is image.secret (singular), not image.secrets (plural map). Fuzzball rejects a v4 workflow that uses the plural form at submit time, with the validation error now unsupported: please use secret. Always use the singular secret field for image pull credentials.

Secret References in Services

The services section of a workflow supports the same secret reference patterns as the jobs section:

  • Image pull secrets: referenced via image.secret
  • Image decryption secrets: referenced via image.decryption-secret
  • Environment variable secrets: referenced using secret:// URIs in the env block

For example, a service referencing a private container registry and environment secrets:

services:
  web-server:
    image:
      uri: docker://privaterepo/nginx:latest
      secret: secret://user/my-oci-secret
    command: ["nginx", "-g", "daemon off;"]
    env:
      - DATABASE_PASSWORD=secret://user/db-credentials
      - API_KEY=secret://user/api-key

Image secret scopes (user, group, organization, cluster) apply the same access control rules in services as they do in jobs, and the account scope is accepted as a legacy alias for group. Environment variable secrets must use the user scope.

When using Fuzzball Federate, the secrets a service references – its image secret, its image decryption secret and its environment secrets – are materialized for the downstream cluster alongside the ones a job references. No additional configuration is required.