Deployment
After fulfilling the prerequisites from the requirements doc, you are ready to deploy Federate in an existing K8s cluster that is already support Fuzzball.
If you are running kubectl on the same node that is hosting the K8s installation and Fuzzball
Orchestrate deployment (common in on-prem deployments) then you don’t need to worry about setting up
a kubeconfig file. If you are using the kubectl command on a local host to control a K8s
deployment on a remote server (common in a cloud deployment) you will need to double check that your
kubeconfig file is pointing at the right cluster.
In AWS, the command to update your kubeconfig file will look something like the following:
$ aws eks update-kubeconfig --region us-east-1 --name <cluster name and ID>
Check the Cloud Admin Guides for information on retrieving the appropriate command to update your kubeconfig file.
Fuzzball Federate uses the Fuzzball operator that was already installed to deploy your Fuzzball
Orchestrate cluster with a new Custom Resource Definition (CRD) file. We’ll call this file
fuzzball-federate.yaml. Many of the values are predetermined, but you there are some values you
need to supply for your particular installation.
You can create an appropriate fuzzball-federate.yaml file by populating the following environment
variables with their correct values and running the cat command to create the file.
Fill in your CIQ depot credentials here:
$ DEPOT_USER="" # populate with your username for CIQ Depot
$ ACCESS_KEY="" # populate with the Depot key obtained from the CIQ sales/support team
Decide on the version of Federate that you want to deploy (recommend v2.1.8 at time of writing):
$ FED_VERSION=v2.1.8 # change as necessary
You need to determine the certificate issuer for your externally facing URLs. This is set at
Fuzzball deployment. In the AWS marketplace, it will be letsencrypt-prod. On prem, your
deployment may have (insecure) self-signed certificates in which case the appropriate value will be
internal-ca-issuer, it might be letsencrypt-prod if you used letsencrypt, or it could be another
issuer. You can find this information with kubectl get clusterissuer.
$ CERT_ISSUER=letsencrypt-prod # change as necessary
You will need to supply the domain where the cluster is hosted, the realm ID of the keycloak instance, and the email address that was set as the owner of the keycloak instance. You can obtain this information as described here.
$ DOMAIN=myfuzzballdomain.com # change as necessary
$ KC_REALMID=$(uuidgen --random)
$ KC_EMAIL="" # populate with the keycloak owner email address
Once you have all of these environment variables set in your terminal, you can copy and paste the
following code block to create the fuzzball-federate.yaml file in your current working directory
with the values you chose.
The examplefuzzball-federate.yamlconfigures the Federate audit service and database to use storage local to the nodes running on EKS.
$ cat >fuzzball-federate.yaml<<EOF
apiVersion: deployment.ciq.com/v1alpha1
kind: FuzzballFederate
metadata:
labels:
app.kubernetes.io/name: fuzzball-federate
app.kubernetes.io/part-of: fuzzball
name: fuzzball-federate
spec:
image:
repository: depot.ciq.com/fuzzball/fuzzball-images
username: ${DEPOT_USER}
password: ${ACCESS_KEY}
exclusive: false
fuzzball:
version: ${FED_VERSION}
cluster:
kind: FEDERATE
audit:
storage:
class: local-path
localStorage: true
database:
create:
enableDebugPod: true
storage:
class: local-path
tls:
# Externally facing issuer, likely letsencrypt but could be something else.
# Issuers in the cluster can be found with 'kubectl get clusterissuer'.
ingressIssuer:
external:
internalCAIssuerName: ${CERT_ISSUER}
internalIssuer:
external:
internalCAIssuerName: internal-ca-issuer
# Assumes existing Kong deployment from FuzzballOrchestrate
ingress:
external:
domain: federate.${DOMAIN}
className: kong
keycloak:
create:
createDatabase: true
realmId: ${KC_REALMID}
username: keycloak
password: keycloak
ownerEmail: ${KC_EMAIL}
EOF
Now you can run the following command to deploy Federate into the K8s that supports your Fuzzball Orchestrate installation.
$ kubectl apply -f fuzzball-federate.yaml
And you can watch as the Fuzzball Operator carries out the deployment of Federate in your K8s cluster like so. The process usually takes 10 or 15 minutes to complete.
$ kubectl logs -l app.kubernetes.io/name=fuzzball-operator -n fuzzball-system -f --tail=-1
[snip...]
Resources:
~ 3 updated
136 unchanged
Duration: 4s
2025-03-13T17:13:00Z DEBUG events Resources have been deployed successfully {"type": "Normal", "object": {"kind":"FuzzballFederate","name":"fuzzball-federate","uid":"6bdda038-b41c-489d-9ec9-f2fb5311388a","apiVersion":"deployment.ciq.com/v1alpha1","resourceVersion":"412932"}, "reason": "DeploymentSucceeded"}
2025-03-13T17:13:00Z INFO Updated Fuzzball status to ReconciliationComplete - Reconciliation completed successfully {"controller": "fuzzballfederate", "controllerGroup": "deployment.ciq.com", "controllerKind": "FuzzballFederate", "FuzzballFederate": {"name":"fuzzball-federate"}, "namespace": "", "name": "fuzzball-federate", "reconcileID": "a63ae801-a7fb-40d1-a733-bf3582bfd463"}
At this point, you can access your new Federate cluster and configure it to point to your existing Fuzzball Orchestrate cluster(s).