Deployment

If there are any left-over stacks or resources from a previous deployment they may interfere with your ability to deploy a fresh Fuzzball cluster. Please make sure that all stacks, nested stacks, and resources from previous deployments have been fully and successfully deleted before initiating a new one. You can use the following command to forcibly remove old Fuzzball resources after destroying your CloudFormation stack if necessary:

$ fuzzball cluster aws cleanup

Make sure you are logged into your AWS account as the fuzzballAdmin IAM user and navigate to the Fuzzball Cloud Marketplace listing. Review the information paying special attention to the pricing options. When you are ready to subscribe, press the “View Purchase Options” button.

On the subscription page you can accept the public or private offer

After subscribing, you can press the “Launch your Software” button.

The launch page will include a link to the AWS CloudFormation page as well as the link to the CloudFormation template for your selected version of Fuzzball. Note down the highlighted URI of the template.

With the template URI in hand you can head over to the CloudFormation page either by following the link on the launch page or going directly to CloudFormation in the AWS console. On the CloudFormation page select “Create stack” and on the following page add the Fuzzball CloudFormation template URI

Make sure you are in the region where you want to install Fuzzball and where you have the appropriate service quotas configured. Use the dropdown on the top right to change to the correct region if necessary.

After clicking “Next” you will be taken to the configuration form. Here, you can supply the values that are specific to your Fuzzball cluster.

• ClusterAdminArns: A comma-separated list of IAM user ARNs and/or role ARNs that will have admin access to the Kubernetes cluster through the AWS UI or kubectl. You can mix user and role ARNs in a single value. Use the full ARN format:

  • User: arn:aws:iam::<account-id>:user/<name> (e.g., the fuzzballAdmin user from the previous section)
  • Role: arn:aws:iam::<account-id>:role/<name> (for SSO users)

  Do not use the arn:aws:sts assumed-role format returned by aws sts get-caller-identity.

At least one cluster admin ARN must be specified. Without a cluster admin, you will not be able to access the EKS cluster via kubectl to retrieve the Kubernetes secrets needed for configuring Fuzzball contexts.

• Domain: This is the domain name of the Hosted Zone that you should have configured in Route53 by either purchasing a new domain, or creating a new Hosted Zone and adding it to the DNS records of your existing top-level domain. See the section on setting up a hosted zone with Route53 in the appendices for more details.

• DomainHostedZoneID: This is the actual ID of the Hosted Zone that you should have configured in Route53. Once again, see the section on setting up a hosted zone with Route53 in the appendices for more details.

• PostgresEngineVersion: Fuzzball supports the v16.x series of the PostgreSQL engine. New point versions within the v16.x series are regularly available, and older versions are automatically deprecated when newer versions are released. This means that the version that is pre-filled in the CloudFormation form may be deprecated. To avoid this issue, it is recommended that you run the following command and locate the latest version in the v16.x series. In this example, you would place 16.6 in the PostgresEngineVersion field.

• EnableRDSDeletionProtection: When this parameter is set to true, it will prevent the AWS RDS instance deployed by the CloudFormation template from being deleted. By default, this parameter is set to false.

• EnableRDSDRSnapshot: When this parameter is set to true, it will enable automated RDS backup replication in a secondary region. By default, this parameter is set to true.

$ aws rds describe-db-engine-versions --engine postgres \
    --query 'DBEngineVersions[].EngineVersion' --output json | \
    grep "^\s*\"16\.[0-9]*\""

    "16.4",
    "16.5",
    "16.6",

• InitialInstanceTypes: A comma-separated list of EC2 instance types to pre-configure as compute node definitions once your Fuzzball cluster is deployed (e.g., t3a.2xlarge,p3.2xlarge). If left empty, no instance types are pre-configured and you can add them manually after deployment. Make sure your account has sufficient quotas for any instance types you include here.

• OverwriteInstanceTypes: When set to true, replaces all existing compute node definitions with the types listed in InitialInstanceTypes, including clearing them entirely when InitialInstanceTypes is empty or blank. When false, existing definitions are left in place regardless of what InitialInstanceTypes contains. When updating a cluster via the Fuzzball CLI with --instance-types, this parameter is set to true automatically and that value persists in the CloudFormation stack. Subsequent updates that do not pass --instance-types will continue to overwrite compute node definitions until OverwriteInstanceTypes is explicitly reset to false in the stack parameters.

In addition, there are parameters that relate to third-party components that fuzzball utilizes within its stack. Below are these parameters with more context about the dependencies they correspond to.

• Keycloak: Fuzzball utilizes Keycloak as its main authentication provider. A Keycloak instance is deployed by the operator and torn down with the cluster. Keycloak provides fuzzball with SSO, user management, and secure authentication/authorization for Fuzzball users and services.

  • KeycloakRealmName: The name of the Keycloak realm to be created for your deployment. The realm name will also be used as the organization name by Fuzzball.

  • KeycloakOwnerEmail: The email address of the owner or administrator for the Keycloak realm.

  • KeycloakUsername: The username for the Keycloak admin account. This account will have administrative privileges within the master realm. By default, the username will be “keycloak”

  • KeycloakPassword: The password for the Keycloak admin account (KeycloakUsername).

  • KeycloakDefaultUserPassword: The default password assigned to new users created in the Keycloak realm, including the organization owner.

• Let’s Encrypt: Fuzzball utilizes Let’s Encrypt to automatically provision and manage TLS certificates, enabling secure HTTPS connections for its services. Let’s Encrypt is deployed by the operator and torn down with the cluster

  • LetsEncryptEmail: The email address that will be associated with the Let’s Encrypt account for your deployment

Once you’ve filled in the appropriate values and pressed next, you will be presented with several optional configuration parameters. You can fill these in as your use-case dictates, and then check the two acknowledgement boxes at the bottom of the page if you understand the permissions you are giving Fuzzball.

After clicking “Next” you will be presented with one more screen to review all of the parameters you provided and create your cluster.

Once you are satisfied with the options you have chosen you can select “Submit”. You will be presented with a screen to watch your cluster as it is deployed. There are several options available for watching the various services in your stacks and nested stacks as they are deployed.

During the deployment process, CloudFormation establishes all of the resources necessary to host the Fuzzball stack, and then the Fuzzball Kubernetes operator deploys the Kubernetes Orchestrate platform. These steps take about 90 minutes and 30 minutes respectively, so the entire deployment usually takes around 2 hours to complete.

Once the main stack reports that it is in the Completed state, you can begin configuring and using Fuzzball.

In order to run the deployment, we have to create a few IAM roles to establish the required permissions. Each of these roles have their AssumeRolePolicy scoped to the relevant AWS service and therefore can not be used by a user. In addition, each policy is scoped either to a specific set of resources, or requires explicit tagging in order to apply said access. Meaning the roles can only affect fuzzball resources in your account.

• ECSRunnerLambdaExecutionRole: This role defines the permissions the lambda needs to trigger the pulumi runner. It can only be assumed by the lambda service. It focuses on giving permission to start and manage ecs tasks in the ecs cluster.

• FuzzballPulumiRunnerTaskExecutionRole: This role defines the permissions needed to create the container the pulumi runner will use. It is used by the FuzzballPulumiRunnerTaskDefinition. It can only be assumed by the ecs service. It gives access to pull the image from our marketplace repository, and adds some ec2 resources to the container.

• FuzzballPulumiRunnerTaskRole: This role defines the permissions needed to run the pulumi program that deploys Fuzzball and its dependencies. Because of the varied resource footprint, it mentions many actions. The permissions themselves are broken up into multiple managed policies also included in the template (FuzzballPulumiRunnerTaskRolePolicyECRS3KMS, FuzzballPulumiRunnerTaskRolePolicySTSRDSEFS, etc). It can only be assumed by the ecs service.

As an alternative to the CloudFormation console workflow above, you can deploy and manage Fuzzball on AWS directly from the Fuzzball CLI using the fuzzball cluster aws subcommands.

Before deploying, run the preflight check to verify that required AWS service-linked IAM roles exist and review quota guidance:

$ fuzzball cluster aws preflight

Use --provision-roles to automatically create any missing roles:

$ fuzzball cluster aws preflight --provision-roles

You can also pass --provision-roles directly to fuzzball cluster aws deploy to create missing service-linked roles as part of deployment in a single step.

Deploy a new cluster interactively:

$ fuzzball cluster aws deploy

For non-interactive deployments, supply all parameters as flags. The --cluster-admin-arns flag is required and accepts a comma-separated list of IAM ARNs that will be granted admin access to the EKS cluster. You can mix user ARNs and role ARNs in a single value:

$ fuzzball cluster aws deploy \
  --domain "$DOMAIN" \
  --organization-admin "admin@example.com" \
  --cluster-admin-arns "arn:aws:iam::123456789012:user/fuzzballAdmin" \
  --instance-types "t3a.2xlarge,p3.2xlarge" \
  --non-interactive

For SSO role ARNs, use the IAM role ARN format (arn:aws:iam::<account>:role/<name>), not the STS assumed-role ARN returned by aws sts get-caller-identity (arn:aws:sts::<account>:assumed-role/<role>/<session>). The assumed-role format will not work because EKS maps access using the underlying IAM role, not the temporary STS session.

Preflight checks run automatically before deploy. Pass --skip-preflight to bypass them.

Once deployed, the following subcommands let you manage the cluster:

Use fuzzball cluster aws <subcommand> --help for the full list of options for each command.

You can stream pod logs from your EKS cluster without needing direct kubectl access using the fuzzball cluster aws logs command:

$ fuzzball cluster aws logs [flags]

Common flags:

Examples:

# List available components
$ fuzzball cluster aws logs --component ""

# Stream orchestrator logs
$ fuzzball cluster aws logs --component fuzzball-orchestrate -f

# Show the last 100 lines from a specific pod
$ fuzzball cluster aws logs --pod fuzzball-orchestrate-xxxxx --tail 100

If there are any left-over resources from a previous deployment in your GCP project, they may interfere with your ability to deploy a fresh Fuzzball cluster. Please make sure that all resources from previous deployments have been fully and successfully deleted before initiating a new one. You can use the following command to forcibly remove old Fuzzball resources after destroying your GCP deployment if necessary:

$ fuzzball cluster gcp cleanup

To deploy Fuzzball in GCP, you must log in via Helm to the OCI registry that you set up during the Requirements section.

To create an access token and use it to log into the OCI registry via Helm, execute the following command:

$ gcloud auth configure-docker ${REGION}-docker.pkg.dev

$ gcloud auth print-access-token | helm registry login ${REGION}-docker.pkg.dev \
  --username oauth2accesstoken \
  --password-stdin

This token is short-lived (~1 hour). If a deployment takes longer than that, re-run helm registry login with a fresh token. The gcloud auth configure-docker step configures the OCI credential helper and only needs to be run once.

Once you are logged in, you are ready to deploy Fuzzball!

The simplest way to deploy is using interactive mode.

Include the --dry-run flag to get an idea of what will happen before you actually execute the command.

$ fuzzball cluster gcp deploy
Select GCP project:
  > some-project (some-project)
Select GCP region:
  > us-central1 (Iowa)
 SUCCESS  GCP authentication verified for project 'some-project'

 INFO  GCP Account Information:

  Project ID:   some-project
  Project Name: some-project
  Region:       us-central1

Proceed with deployment to this GCP project?:
  > Yes
 INFO  Using CLI version: v3.4.0
 INFO  Loading embedded Infrastructure Manager template...
 SUCCESS  [ok] Infrastructure Manager template loaded
Domain name [Required]: :

The CLI will prompt you for all required parameters including the following:

• GCP project
• Region and zone
• Fuzzball version (defaults to the CLI version if omitted)
• Domain name
• Organization owner email

For non-interactive deployments, you can use the following. (See the Requirements section for information on setting these environment variables.)

$ fuzzball cluster gcp deploy \
  --project "$PROJECT_ID" \
  --region "$REGION" \
  --zone "$ZONE" \
  --version "$VERSION" \
  --domain "$SELECTED_DOMAIN" \
  --dns-zone-name "$MANAGED_ZONE" \
  --dns-zone-project "$PROJECT_ID" \
  --keycloak-owner-email "admin@example.com" \
  --deployment-name "unique-name" \
  --node-pool-machine-type "n2-standard-16" \
  --instance-types=n1-standard-4,n2-standard-8,g2-standard-8 \
  --non-interactive

SUCCESS: GCP authentication verified for project 'some-project'

INFO: GCP Account Information:

  Project ID:   some-project
  Project Name: some-project
  Region:       us-central1

INFO: Non-interactive mode: proceeding with GCP account automatically
INFO: Loading embedded Infrastructure Manager template...
SUCCESS: [ok] Infrastructure Manager template loaded

INFO: Required Configuration

SUCCESS: [ok] FuzzballVersion: v3.4.0
SUCCESS: [ok] Domain: fuzzball-testing-is-awesome.org
SUCCESS: [ok] KeycloakOwnerEmail: admin@example.com
SUCCESS: [ok] LetsEncryptEmail: admin@example.com
SUCCESS: [ok] KeycloakPassword: [provided]
SUCCESS: [ok] KeycloakDefaultUserPassword: [provided]

[...snip]
SUCCESS: Pulumi runner execution completed successfully
SUCCESS: [ok] Pulumi create completed successfully
Waiting for Fuzzball operator to become ready...
SUCCESS: Fuzzball operator is ready
SUCCESS: Created fuzzball context "my-fuzzball"
INFO:   To login: fuzzball context login

INFO: Deployment Information:

  Deployment Name: my-fuzzball
  Project ID:      some-project
  Region:          us-central1
  Domain:          fuzzball-is-awesome.org

INFO: Generated Credentials:
  Keycloak Admin Password: ********** (16 chars)
  Keycloak Default User Password: ********** (12 chars)

INFO: Credentials have been configured for your deployment. Use the deployment status command to verify.

INFO: To check the status of your deployment:
  fuzzball cloud gcp status --project some-project --deployment-name my-fuzzball

INFO: To configure kubectl access:
  gcloud container clusters get-credentials <cluster-name> --project some-project --region us-central1

INFO: Fuzzball URLs (once DNS propagates):
  UI:         https://ui.fuzzball-is-awesome.org
  API:        https://api.fuzzball-is-awesome.org
  Keycloak:   https://keycloak.fuzzball-is-awesome.org

For a full list of the options and arguments that can be specified during deployment, use the fuzzball cluster gcp deploy --help command.

If you see an error indicating that the Pulumi runner failed, or the deployment appears successful but nothing is actually running, verify the deployment with the supported status and info commands documented on this page before taking further action.

The Pulumi runner command is an internal/hidden recovery mechanism and is not part of the supported public CLI workflow. If verification shows the deployment is incomplete or unhealthy, follow your organization’s internal recovery procedure or contact support instead of rerunning the hidden command directly.

As part of every GCP deployment, Fuzzball automatically mounts the GCP Filestore NFS volume and creates the ephemeral/ and persistent/ subdirectories required by the NFS CSI driver. This initialization runs as a short-lived Kubernetes Job and does not require any manual steps.

A successful deployment will create a fuzzball cli context for the cluster in ${XDG_CONFIG_HOME:-$HOME/.config}/fuzzball/fuzzball.yaml and print out a basic summary of the cluster properties including commands to set up kubectl access to the underlying Kubernetes cluster (see below). You can also obtain similar information later by running

$ fuzzball cluster gcp info --project $PROJECT_ID --region $REGION

 SUCCESS  GCP authentication verified for project 'PROJECT'
 INFO  Searching for Fuzzball deployments to view info for...
 SUCCESS  Found 1 Fuzzball deployment(s):

  1. DEPLOYMENT_NAME (Version: v3-3-0, Region: us-central1, Status: ACTIVE)

 INFO  Using deployment: DEPLOYMENT_NAME

 INFO  Deployment Information

  Deployment:     DEPLOYMENT_NAME
  Project:        PROJECT
  Region:         REGION
  Status:         ACTIVE
  Version:        v3.4.0
  Domain:         DOMAIN
  Created:        2026-04-08t09-20-19z

 INFO  Cluster URLs

  API:            https://api.DOMAIN
  UI:             https://ui.DOMAIN
  Keycloak:       https://auth.DOMAIN

 INFO  Context Configuration

  To connect the Fuzzball CLI to this deployment, run:

    fuzzball context create DEPLOYMENT_NAME \
      --api-url https://api.DOMAIN \
      --auth-url https://auth.DOMAIN

    fuzzball context use DEPLOYMENT_NAME

You can use Kubernetes through the kubectl command to monitor your cluster as it deploys and to manage the underlying pods and resources. First you need to configure your local kubectl installation to use your GCP deployment. Issue the following commands:

$ gcloud container clusters list --project=$PROJECT_ID --region=$REGION
NAME            LOCATION     MASTER_VERSION      MASTER_IP       MACHINE_TYPE   NODE_VERSION        NUM_NODES  STATUS   STACK_TYPE
<cluster-name>  us-central1  1.35.3-gke.1234000  104.198.16.117  n2-standard-8  1.35.3-gke.1234000  3          RUNNING  IPV4

This will give you your cluster name. Now you can use it to execute the following. (Replace <cluster-name> with the value you obtained from the previous command.)

$ gcloud container clusters get-credentials <cluster-name> --project $PROJECT_ID --region $REGION
Fetching cluster endpoint and auth data.
kubeconfig entry generated for <cluster-name>.

You may need to install the gke-gcloud-auth-plugin package and rerun the command above if it fails.

You now have enough information to proceed to the Initial Configuration section and log in and finish setting your cluster up.

At this point you can also run commands like the following to monitor your deployment and check the health of your cluster:

$ kubectl logs -l app.kubernetes.io/name=fuzzball-operator -n fuzzball-system -f --tail=-1
[snip...]
Resources:
    ~ 4 updated
    253 unchanged

Duration: 23s

2026-04-27T19:29:08Z	DEBUG	events	Resources have been deployed successfully	{"type": "Normal", "object": {"kind":"FuzzballOrchestrate","name":"some-cluster","uid":"48d17325-2ed4-4cd0-8a1e-1a3c5c1ed0d1","apiVersion":"deployment.ciq.com/v1alpha1","resourceVersion":"1777317722455023010"}, "reason": "DeploymentSucceeded"}
2026-04-27T19:29:08Z	INFO	Updated Fuzzball status to ReconciliationComplete - Reconciliation completed successfully	{"controller": "fuzzballorchestrate", "controllerGroup": "deployment.ciq.com", "controllerKind": "FuzzballOrchestrate", "FuzzballOrchestrate": {"name":"some-cluster"}, "namespace": "", "name": "some-cluster", "reconcileID": "e157a9b8-2a23-4d17-8780-407a93738fd3"}

$ kubectl get pods -n fuzzball
NAME                                         READY   STATUS      RESTARTS   AGE
fuzzball-admin-0                             1/1     Running     0          106m
fuzzball-agent-dd9fd9f45-5x6b6               1/1     Running     0          104m
fuzzball-agent-dd9fd9f45-75mcr               1/1     Running     0          104m
fuzzball-agent-dd9fd9f45-jmgwm               1/1     Running     0          105m
fuzzball-audit-74cc4c67f4-9d6tb              1/1     Running     0          105m
fuzzball-audit-74cc4c67f4-fjj87              1/1     Running     0          105m
fuzzball-audit-74cc4c67f4-r6464              1/1     Running     0          106m
fuzzball-auth-spicedb-684c7ccf5c-5jpln       1/1     Running     0          105m
fuzzball-auth-spicedb-684c7ccf5c-8fhf8       1/1     Running     0          106m
fuzzball-auth-spicedb-684c7ccf5c-srg5t       1/1     Running     0          105m
fuzzball-catalog-sync-29622000-vwsw2         0/1     Completed   0          70m
fuzzball-cluster-admin-697df8c4b4-rg8t8      1/1     Running     0          105m
fuzzball-cluster-admin-697df8c4b4-t5l6s      1/1     Running     0          105m
fuzzball-cluster-admin-697df8c4b4-tvj5b      1/1     Running     0          105m
fuzzball-jetstream-0                         1/1     Running     0          105m
fuzzball-jetstream-1                         1/1     Running     0          105m
fuzzball-jetstream-2                         1/1     Running     0          105m
fuzzball-load-default-catalog-k59qx          0/1     Completed   0          102m
fuzzball-openapi-5448cc4cc4-4n9vs            1/1     Running     0          105m
fuzzball-openapi-5448cc4cc4-72p4j            1/1     Running     0          105m
fuzzball-openapi-5448cc4cc4-vc8vr            1/1     Running     0          106m
fuzzball-orchestrator-54d7f486b8-phthq       1/1     Running     0          103m
fuzzball-resource-defs-setup-nnbjp           0/1     Completed   0          102m
fuzzball-storage-74d665f495-22k58            1/1     Running     0          103m
fuzzball-storage-74d665f495-qt2lz            1/1     Running     0          103m
fuzzball-storage-74d665f495-wxhlx            1/1     Running     0          103m
fuzzball-storage-setup-rvsfv                 0/1     Completed   0          102m
fuzzball-substrate-bridge-6bb695bbf4-8tqcj   1/1     Running     0          104m
fuzzball-substrate-bridge-6bb695bbf4-flckj   1/1     Running     0          104m
fuzzball-substrate-bridge-6bb695bbf4-gjmd6   1/1     Running     0          104m
fuzzball-ui-665dbdf7f8-x25t7                 1/1     Running     0          105m
fuzzball-workflow-76bddf9f5c-8gtjv           1/1     Running     0          102m
fuzzball-workflow-76bddf9f5c-95bqw           1/1     Running     0          103m
fuzzball-workflow-76bddf9f5c-mndzf           1/1     Running     0          102m

The fuzzball cluster gcp info or the deployment-info-wait.sh script referenced in the initial login section display a command to create the appropriate context to add and log into your cluster along with the credentials needed for the automatically provisioned users including the cluster admin user. Once you have done so, you can use the fuzzball command directly to monitor and manage many aspects of your deployment.

For instance, the list, status, info, and logs commands allow you to view information about your running deployment(s).

And the update, destroy, and cleanup commands allow you to manage your cluster directly.

Use the --help flag in the CLI to list these commands and see information about running each of them.

You can stream pod logs from your GKE cluster without needing direct kubectl access using the fuzzball cluster gcp logs command:

$ fuzzball cluster gcp logs --project $PROJECT_ID --region $REGION [flags]

Common flags:

Examples:

# List available components
$ fuzzball cluster gcp logs --project $PROJECT_ID --region $REGION --component ""

# Stream orchestrator logs
$ fuzzball cluster gcp logs --project $PROJECT_ID --region $REGION \
    --component fuzzball-orchestrate -f

# Show the last 100 lines from a specific pod
$ fuzzball cluster gcp logs --project $PROJECT_ID --region $REGION \
    --pod fuzzball-orchestrate-xxxxx --tail 100

Support for CoreWeave within Fuzzball is in preview status and is currently subject to more rapid change to address customer requirements than other features of Fuzzball. If you are interested in using Fuzzball on CoreWeave, we recommend contacting CIQ as part of your deployment planning process.

After fulfilling the prerequisites listed in the requirements and discovering your cluster’s domain using the domain discovery procedure, you are ready to deploy Fuzzball on CoreWeave.

The Fuzzball operator manages the deployment and lifecycle of Fuzzball on your Kubernetes cluster.

First, use your Depot credentials to authenticate with the Helm registry:

$ DEPOT_USER="your-depot-username"

$ ACCESS_KEY="your-depot-access-key"

Replace your-depot-username and your-depot-access-key with the credentials provided by CIQ.

$ helm registry login depot.ciq.com --username "${DEPOT_USER}" --password "${ACCESS_KEY}"

Install the Fuzzball operator using the Helm chart from the depot:

$ VERSION="v3.4.0"

$ CHART="oci://depot.ciq.com/fuzzball/fuzzball-images/helm/fuzzball-operator"

$ STORAGE_CLASS="shared-vast"

$ helm upgrade --install fuzzball-operator "${CHART}" \
  --namespace fuzzball-system \
  --create-namespace \
  --version "${VERSION}" \
  --set "image.tag=${VERSION}" \
  --set "imagePullSecrets.name=repository-ciq-com" \
  --set "imagePullSecrets.inline.registry=depot.ciq.com" \
  --set "imagePullSecrets.inline.username=${DEPOT_USER}" \
  --set "imagePullSecrets.inline.password=${ACCESS_KEY}" \
  --set "storageClassName=${STORAGE_CLASS}"

Check that the operator pod is running:

$ kubectl get pods -n fuzzball-system
NAME                                              READY   STATUS    RESTARTS   AGE
fuzzball-operator-controller-manager-xxxxx-xxxxx  2/2     Running   0          2m

Expected output should show the operator pod in Running state with 2/2 containers ready.

Create a FuzzballOrchestrate custom resource to deploy Fuzzball on CoreWeave. Here’s a complete example configuration:

apiVersion: deployment.ciq.com/v1alpha1
kind: FuzzballOrchestrate
metadata:
  name: fuzzball-coreweave
  namespace: fuzzball-system
spec:
  # Image registry configuration
  image:
    username: <depot-username>
    password: <depot-password>
    exclusive: false

  # Database configuration
  database:
    create:
      enableDebugPod: false
      storage:
        class: shared-vast

  # Fuzzball version and cluster configuration
  fuzzball:
    version: v3.4.0
    cluster:
      name: fuzzball-coreweave

    # CoreWeave provisioner configuration
    orchestrator:
      provisioner:
        enabled: true
        coreweave:
          enabled: true
          storage:
            accessMode: ReadWriteMany
            class: shared-vast
            size: 100Gi  # Adjust based on workflow needs

    # Shared container image cache
    config:
      sharedPVC:
        accessMode: ReadWriteMany
        class: shared-vast
        size: 10Gi  # Adjust based on caching needs

  # Ingress and networking configuration
  ingress:
    create:
      # Use your discovered CoreWeave domain
      domain: <YOUR_COREWEAVE_DOMAIN>
      proxy:
        type: LoadBalancer
        annotations:
          # Public LoadBalancer for internet access
          service.beta.kubernetes.io/coreweave-load-balancer-type: public
          # Wildcard DNS for all services
          service.beta.kubernetes.io/external-hostname: '*.<YOUR_COREWEAVE_DOMAIN>'

  # Keycloak identity management
  keycloak:
    create:
      createDatabase: true
      # Generate with: uuidgen
      realmId: <uuid-v4-realm-id>
      ownerEmail: <owner-email>
      # Change this password after first login!
      defaultUserPassword: <initial-user-password>

  # TLS certificate configuration
  tls:
    # cert-manager for certificate management
    certManager:
      create: {}
    # trust-manager for CA certificate distribution
    trustManager:
      create: {}
    # Let's Encrypt certificate issuer
    ingressIssuer:
      create:
        letsEncrypt:
          email: <letsencrypt-email>
          issuer: letsencrypt-prod

Replace the placeholder values with your configuration. Use the domain discovered in the domain discovery procedure.

For detailed explanations of these configuration options and additional settings, see the CRD reference material.

If your cluster already has cert-manager installed, you can configure Fuzzball to use it instead of deploying a new instance. See Deploying with External cert-manager for details.

Save the configuration to a file and apply it with kubectl:

$ kubectl apply -f fuzzball-orchestrate-coreweave.yaml

Watch the deployment status:

$ kubectl get fuzzballorchestrate -A -w

Wait until the status shows Ready. This typically takes several minutes for a full deployment.

Check the deployed resources:

$ kubectl get fuzzballorchestrate -A

$ kubectl get pvc -n fuzzball

$ kubectl get pods -n fuzzball

For detailed deployment status and troubleshooting, check the operator logs:

$ kubectl logs -l control-plane=fuzzball-operator-controller-manager -n fuzzball-system -f

The deployment steps above configure dynamic provisioning, where Fuzzball creates and destroys CoreWeave nodes on-demand. If you prefer to manage node pools yourself for predictable capacity or faster startup times, see Static Node Pool Provisioning for an alternative deployment approach.

Support for Oracle Cloud Infrastructure (OCI) within Fuzzball is in preview status and is currently subject to more rapid change to address customer requirements than other features of Fuzzball. If you are interested in using Fuzzball on OCI, we recommend contacting CIQ as part of your deployment planning process.

After fulfilling the prerequisites listed in the requirements, you are ready to deploy Fuzzball on Oracle Cloud Infrastructure using the Fuzzball CLI.

Before deploying, ensure the OCI CLI is installed and configured with your tenancy credentials.

$ oci setup config

This creates a configuration file at ~/.oci/config with your tenancy OCID, user OCID, region, and API key. Verify the configuration is working:

$ oci iam region list --output table

The Fuzzball CLI is used to deploy and manage Fuzzball clusters on OCI. Installation instructions for various operating systems are available in the Installing the CLI appendix.

The Fuzzball CLI provides an interactive deployment flow that guides you through the required configuration parameters. Run the deployment command:

$ fuzzball cluster oci deploy

The CLI will prompt you for the following configuration:

• Tenancy OCID — Your OCI tenancy identifier
• Compartment OCID — The compartment where resources will be created
• Region — The OCI region for deployment (e.g., us-phoenix-1)
• Fuzzball Version — The version of Fuzzball to deploy
• Domain — The domain name for your Fuzzball cluster
• Keycloak Configuration — Realm name, owner email, and admin credentials
• Let’s Encrypt Email — Email for TLS certificate management
• Compute Shapes — Standard and GPU shapes for compute nodes

You can also provide these values non-interactively using CLI flags:

$ fuzzball cluster oci deploy \
    --version "v3.4.0" \
    --domain "fuzzball.example.com" \
    --compartment-ocid "ocid1.compartment.oc1..example" \
    --region "us-phoenix-1" \
    --non-interactive

Use the --dry-run flag to preview the deployment configuration without creating any resources:

$ fuzzball cluster oci deploy --dry-run

After you confirm the deployment configuration, the CLI creates an OCI Resource Manager stack and submits an Apply job to provision the infrastructure.

The CLI streams progress from the OCI Resource Manager Apply job as infrastructure is provisioned. The deployment typically takes 30-60 minutes depending on the resources being created.

If you need to check status after the initial deployment command has completed, use:

$ fuzzball cluster oci status \
    --compartment-ocid "ocid1.compartment.oc1..example" \
    --deployment-name "fuzzball"

Once the deployment completes, verify the cluster is accessible at the URLs provided by the CLI:

• UI: https://ui.<your-domain>
• API: https://api.<your-domain>
• Keycloak: https://keycloak.<your-domain>

DNS propagation may take a few minutes after deployment completes. If the URLs are not immediately accessible, wait for DNS records to propagate.

• Compute Shapes: The deployment allows you to configure standard and advanced (GPU) compute shapes. The defaults are appropriate for general workloads, but you can select shapes that match your quota and workload requirements. Additional shapes can be added after deployment.

• DNS Configuration: The deployment creates a DNS zone in OCI and configures the necessary records. If you are using a domain managed outside of OCI, you will need to configure cross-cloud DNS delegation.

• Deletion Protection: The EnableDatabaseDeletionProtection parameter controls whether the PostgreSQL database instance can be deleted. Set this to true for production deployments to prevent accidental data loss.

If you need to remove a Fuzzball deployment and all associated resources, the CLI provides a cleanup command that discovers and deletes Fuzzball-tagged resources in dependency order:

$ fuzzball cluster oci cleanup \
    --compartment-ocid "ocid1.compartment.oc1..example"

Use --dry-run to preview which resources would be deleted without making any changes. In non-interactive environments, the --force flag is required for safety:

$ fuzzball cluster oci cleanup \
    --compartment-ocid "ocid1.compartment.oc1..example" \
    --non-interactive --force

To destroy a specific deployment (including its Resource Manager stack), use:

$ fuzzball cluster oci destroy \
    --deployment-name "fuzzball"