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

Initial Login

To configure your Fuzzball cluster for use, you must first log in. This section will guide you through the process of creating a Fuzzball context and logging in to it as the cluster admin.

For simplicity, you should carry out these steps on the server node hosting Fuzzball orchestrate. You can follow a similar procedure to add contexts and access your Fuzzball cluster from other machines later.

In an AWS deployment you need to set the cluster as your local K8s context to run the convenience script provided by CIQ (see below). For these steps to work, you must have the AWS CLI and the kubectl command installed locally. Check the AWS requirements documentation for more information.

Set your local K8s context to the Fuzzball Cluster

To point your local K8s context to the Fuzzball stack that you just initialized, you need to run aws eks update-kubeconfig with the appropriate parameters. You can find the command that you need to run in the CloudFormation user interface. Go to CloudFormation and highlight the root Fuzzball stack (i.e. the only one that is not listed as “nested”). Then highlight the “Outputs” tab as shown. The appropriate AWS CLI command will appear in the outputs panel.

AWS CLI eks command to set local kubeconfig

Copy that command into your terminal and run it.

$ aws eks update-kubeconfig --region us-east-1 --name aws-fuzzball-24025a48
Added new context arn:aws:eks:us-east-1:123456789012:cluster/aws-fuzzball-24025a48 to /home/user/.kube/config

Installing the Fuzzball CLI

Start by installing the Fuzzball CLI on your server node (or your local machine in the case of AWS) with the following commands:

$ DEPOT_USER="" # populate with your username for CIQ Depot

$ ACCESS_KEY="" # populate with the Depot key obtained from the CIQ sales/support team

$ VERSION="4.4.0-110-g8f0b4aff023d" # matches orchestrate version without the leading v
# dnf install -y https://depot.ciq.com/dlv2/depot-el9.$(uname -m)/depot.rpm

# depot register --user "${DEPOT_USER}" --token "${ACCESS_KEY}"

# depot enable fuzzball

# dnf install -y fuzzball-cli-${VERSION}-1
The $(uname -m) in the Depot client URL selects the x86_64 or aarch64 package. On Rocky Linux 8, use depot-el8 in place of depot-el9. On Rocky Linux 10, install the EL9 package as shown; dnf update depot then moves it to the EL10 build.

Trusting the Cluster Certificate

The minimal Fuzzball configuration used in the on-prem deployment guide causes Fuzzball to be hosted with a self-signed certificate. Since self-signed certificates are not trusted by default, you have to make the CA certificate available to the CLI to avoid validation errors. There are two ways to do this.

You can skip this section in Cloud deployments or if you created a certificate when you performed the deployment.

Option 1: Add the Certificate to the System Trust Store

This approach makes the certificate trusted system-wide for all tools, not just the Fuzzball CLI.

$ kubectl get secret -n cert-manager root-ca-cert -o "jsonpath={.data['ca\.crt']}" | base64 --decode \
    | sudo tee /etc/pki/ca-trust/source/anchors/fb_ca.crt >/dev/null

$ sudo update-ca-trust
When accessing a system with self-signed certificates, the procedure to accept this self-signed certificate should be repeated on other systems that will access the Fuzzball cluster and differs depending on the operating system.

Option 2: Supply the Certificate Directly to the CLI

Use the --ca-file flag or the FUZZBALL_CA_FILE environment variable to supply the CA certificate to the Fuzzball CLI without modifying the system trust store. This is useful when you do not have root access or are scripting across multiple clusters with different CAs.

$ kubectl get secret -n cert-manager root-ca-cert -o "jsonpath={.data['ca\.crt']}" | base64 --decode \
    >/tmp/fuzzball-ca.crt

$ export FUZZBALL_CA_FILE=/tmp/fuzzball-ca.crt

With FUZZBALL_CA_FILE set, all subsequent fuzzball commands in that shell session will trust the specified CA automatically.

The --insecure flag disables TLS certificate verification entirely. It is intended only for development or testing environments and must not be used in production. If both --ca-file and --insecure are set, --insecure takes precedence and --ca-file is ignored with a warning.

Creating Contexts and Logging In

Now download and run the following script to view information about logging into your cluster:

$ wget https://ciq-marketplace-assets.s3.us-east-1.amazonaws.com/public/fuzzball/scripts/deployment-info-wait.sh

$ chmod +x deployment-info-wait.sh

$ ./deployment-info-wait.sh

-------------------CLUSTER INFORMATION--------------------

Keycloak URL:     https://auth.10.1.96.99.nip.io/auth/realms/62c4aca0-7b38-4972-9300-7d17472a0fcc
Fuzzball API URL: https://api.10.1.96.99.nip.io
Fuzzball UI URL:  https://ui.10.1.96.99.nip.io

Fuzzball admin account:
- username: user@domain.com
- password: fbpassword

Fuzzball cluster admin account:
- username: fuzzball-admin@local
- password: adminpassword

Keycloak admin account:
- username: keycloak
- password: keycloakpassword

To connect to Fuzzball:

$ fuzzball context create default api.10.1.96.99.nip.io https://auth.10.1.96.99.nip.io/auth/realms/62c4aca0-7b38-4972-9300-7d17472a0fcc fuzzball-cli
$ fuzzball context use default
$ fuzzball context login --direct

To log in as the initial cluster admin, create a local org context:

$ fuzzball context create fuzzball-local api.10.1.96.99.nip.io local fuzzball-cli
$ fuzzball context use fuzzball-local
$ fuzzball context login -u fuzzball-admin@local -p '<password>'

If you have not created a group, you can run:

$ fuzzball group create default
$ fuzzball group use <UUID> # supply the created UUID

Use the information displayed by the script to create the two contexts it describes and to log in to each:

  • default connects through Keycloak as the Fuzzball admin account, the owner of the Fuzzball organization (user@domain.com in the example).
  • fuzzball-local uses local as its authentication method and logs in as the cluster admin account, fuzzball-admin@local. Every deployment creates this user in a built-in Fuzzball Local organization as the cluster’s initial cluster admin. Use this context for cluster admin tasks such as setting up provisioners and managing organizations.

Using the example values above, the commands look like the following. (Use the values that the deployment-info-wait.sh script returned to you instead of the example values shown here.)

Note the single quotes around the passwords in the code block below. The default passwords set up by the Fuzzball CRD often have special characters that require single quotes.
$ fuzzball context create default api.10.1.96.99.nip.io https://auth.10.1.96.99.nip.io/auth/realms/62c4aca0-7b38-4972-9300-7d17472a0fcc fuzzball-cli

$ fuzzball context login --direct -u user@domain.com -p 'fbpassword'

$ fuzzball context create fuzzball-local api.10.1.96.99.nip.io local fuzzball-cli

$ fuzzball context login -u fuzzball-admin@local -p 'adminpassword'

fuzzball context create makes the new context the active one, so each login applies to the context created just before it. Switch between the two afterward with fuzzball context use default and fuzzball context use fuzzball-local.

You can supply usernames and passwords through the FUZZBALL_USER and FUZZBALL_PASSWORD environment variables instead, which keeps them out of shell history. Every CLI flag can be set this way; see the Environment Variables Reference. See Initial Entity Management for more information about local users such as fuzzball-admin@local and how they differ from Keycloak users.

Keycloak is served under the /auth path, so the realm URL is https://auth.<domain>/auth/realms/<realm-id>. A URL without /auth returns Resource not found.
If clients reach the cluster on a node port instead of port 443, set spec.ingress.publicPort (see Public Port). Then include the port in every fuzzball context create command, for example api.<domain>:30443 (and https://auth.<domain>:30443/auth/realms/<realm-id> for a Keycloak context).

Local password login is locked for an account after 5 failed attempts. The CLI then reports too many failed login attempts, try again later. Wrong current passwords entered when changing a local user’s password count toward the same limit. The lock lifts 15 minutes after the fifth failed attempt; retrying while locked does not extend it, but anyone who can reach the API can lock the account again after it lifts by sending 5 more bad passwords. To unlock an account immediately, delete its row from the login_attempts table in the Fuzzball database. The identifier is the lowercased email, with @local appended to a bare username:

DELETE FROM login_attempts WHERE identifier = 'fuzzball-admin@local';

Picking a Group at Login

If you belong to more than one group on the cluster you can drop into a specific group as part of the login itself with --group/-g. The flag accepts the group’s name or UUID, and is honored on local logins as well as the Keycloak device-grant (fuzzball context login) and direct-grant (--direct) flows:

$ fuzzball context login -u <username> -p '<password>' --group SA
Logging into current cluster context...
Group "SA" in use

Without --group, login activates your default group (if one is configured) or falls back to your personal User Account group. You can change the active group at any time after logging in with fuzzball group use <NAME-OR-ID>.

Accepting the Certificate in Your Browser

Your browser does not trust a self-signed certificate either. Unless you import the CA certificate into the browser’s trust store, accept the certificate warning for:

  1. The Fuzzball UI URL that the deployment-info-wait.sh script printed, when you first open the web UI.
  2. The Keycloak URL, when signing in through your organization redirects you there to enter your password. Its certificate is issued by the same CA. Signing in with a local account stays on the UI URL.

Importing the CA certificate into your browser’s trust store covers both.

You do not need to accept the Fuzzball API URL. The web UI sends all of its API requests, including the workflow log stream, to its own server, which reaches the API inside the cluster, so the browser never needs the API’s certificate.

If the UI loads but data such as workflow logs does not appear, the problem is between the UI server and the API, not in your browser. Check the UI server’s logs for API proxy error messages:

$ kubectl logs -n fuzzball deployment/fuzzball-ui | grep "API proxy error"

Reviewing the Active Context

Once you are logged in, fuzzball context show displays the details of the active context along with the profile of the logged-in user:

$ fuzzball context show
Name:            default
Address:         api.fb.local:443
OIDC Server:     https://keycloak.fb.local/realms/e700253c-8ce8-4e36-a420-1e4cab4cb7ef
OIDC Client ID:  fuzzball-cli
Realm:

Group Name:      admin@fb.local
Group ID:        b1558bb2-5130-490e-a231-c8c430053f88

Username:        admin@fb.local
Email:           admin@fb.local
Full Name:       ADMIN ADMIN
Cluster Admin:   yes

The user section is only shown while you are logged in; if the cluster is unreachable or your token has expired, only the context fields are printed. Add -o json or -o yaml for the same details in a structured, machine-readable form. Sensitive fields such as authentication tokens are never included in any output.

If you have assumed another user’s identity (via an admin assume-user token), fuzzball context show prints an ACTING AS banner reminding you whose identity is active and how to return to your own.

Now that you are logged into your Fuzzball cluster, you can proceed to creating an initial basic provisioner configuration.