Admin Commands

This page documents the administrator commands for managing catalog repositories. These commands provide additional capabilities beyond the standard user commands, including the ability to manage repositories system-wide and control individual application template availability.

These commands require administrative privileges in Fuzzball. Regular users should use the user commands instead.

Admin catalog repository commands are accessed under the fuzzball workflow catalog source namespace.

Administrators can add catalog repositories with additional control over repository configuration:

$ fuzzball workflow catalog source add <NAME> <URI> <BRANCH> [flags]

Arguments:

• <NAME>: A descriptive name for the catalog repository
• <URI>: The Git repository URI. HTTPS only – see Restricting repository URIs
• <BRANCH>: The branch to synchronize

Flags:

• --owner-kind: The owner type for the catalog repository (default: group)
  • Options: group, organization, provider
• --access-token, -t: Access token for private repositories
• --id, -i: UUID to assign to this repository (optional)

Example - Add Organization-Wide Repository:

$ fuzzball workflow catalog source add \
    "Official Catalog" \
    "https://github.com/example/official-catalog" \
    "main" \
    --id 22222222-2222-2222-2222-222222222222 \
    --owner-kind organization

Unlike the user import command, the admin add command does not automatically synchronize the repository. You must manually run reload after adding.

Fuzzball clones catalog repositories from the cluster that owns them – orchestrate, or a federate cluster – so a repository URI is a network destination that cluster will connect to. URIs are therefore validated before any connection is made. A URI is always rejected unless it uses the https scheme, names a host without embedded credentials or a fragment, and resolves to a publicly routable address. Loopback, private, link-local, and cloud instance-metadata addresses are refused at connect time, so a hostname that resolves to one of them is refused as well.

These defaults need no configuration. On an operator-managed deployment, the FuzzballOrchestrate or FuzzballFederate resource’s spec.fuzzball.workflowCatalog.restrictions block tightens or deliberately relaxes them:

spec:
  fuzzball:
    workflowCatalog:
      restrictions:
        # Limit catalog repositories to these hosts. Empty accepts any public
        # host. The official catalog's host is always permitted on
        # orchestrate; on a federate cluster list it explicitly.
        allowedHosts:
          - git.internal.example.com
        # Bound the catalog files extracted from a clone (templates, values,
        # metadata, key art). Defaults to 256 MiB.
        maxCloneBytes: 268435456
        # Bound a single clone attempt. Defaults to 2m.
        cloneTimeout: 2m
        # Permit clones that resolve to private or loopback addresses.
        # Development only. Ignored on SaaS deployments.
        allowPrivateAddresses: false

A standalone or compose deployment sets the same keys under a top-level catalogRestrictions block in the orchestrate configuration file, plus rootCaFile, an additional PEM bundle to trust for catalog clones. On an operator deployment use spec.trustedCACerts instead; certificates added there join the pod’s system trust bundle, which catalog clones already use.

Catalog clones honor the standard HTTPS_PROXY / NO_PROXY environment. Behind an egress proxy every clone connects to the proxy, and that connection is not subject to the private-address rule – the proxy decides where it connects onward. The scheme, host, and redirect rules still apply to the repository itself, a repository URI may not name the proxy, and hosts excluded by NO_PROXY are dialed directly and remain subject to the address rule. The active policy and egress mode are logged when the cluster starts.

allowPrivateAddresses disables the address check that prevents a catalog repository from being aimed at internal services. Enable it only on an isolated development deployment. It has no effect on SaaS deployments, where it is always off.

Upgrading: catalog repositories added before this validation existed are not migrated. A repository whose URI uses http, ssh, git, or file, or whose host resolves to a private address, stops syncing and reports the reason in its sync error. Delete it and re-add it over HTTPS – or, for a private Git host on an isolated deployment, set allowPrivateAddresses.

Administrators can reload individual repositories or all repositories at once:

$ fuzzball workflow catalog source reload [--all|<SOURCE>]

Flags:

• --all, -a: Reload all catalog repositories instead of a specific one

Example - Reload All Repositories:

$ fuzzball workflow catalog source reload --all

Administrators can enable or disable individual workflow templates to control their availability in the workflow catalog.

To make a workflow template available in the catalog:

$ fuzzball workflow catalog enable <TEMPLATE_ID>

$ fuzzball workflow catalog disable <TEMPLATE_ID>

Example:

$ fuzzball workflow catalog disable abc12345-6789-def0-1234-56789abcdef0

Disabled templates are not visible in the workflow catalog and cannot be used to create new workflows. Existing workflows created from the template are not affected.

Disabling templates is useful for:

• Temporarily removing outdated or problematic templates without deleting them
• Controlling which templates are available during maintenance periods
• Managing template rollout and deprecation