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.
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}-1The$(uname -m)in the Depot client URL selects the x86_64 or aarch64 package. On Rocky Linux 8, usedepot-el8in place ofdepot-el9. On Rocky Linux 10, install the EL9 package as shown;dnf update depotthen moves it to the EL10 build.
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.
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-trustWhen 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.
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.crtWith FUZZBALL_CA_FILE set, all subsequent fuzzball commands in that shell session will trust the
specified CA automatically.
The--insecureflag disables TLS certificate verification entirely. It is intended only for development or testing environments and must not be used in production. If both--ca-fileand--insecureare set,--insecuretakes precedence and--ca-fileis ignored with a warning.
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 UUIDUse the information displayed by the script to create the two contexts it describes and to log in to each:
defaultconnects through Keycloak as the Fuzzball admin account, the owner of the Fuzzball organization (user@domain.comin the example).fuzzball-localuseslocalas 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/authpath, so the realm URL ishttps://auth.<domain>/auth/realms/<realm-id>. A URL without/authreturnsResource not found.
If clients reach the cluster on a node port instead of port 443, setspec.ingress.publicPort(see Public Port). Then include the port in everyfuzzball context createcommand, for exampleapi.<domain>:30443(andhttps://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 thelogin_attemptstable in the Fuzzball database. The identifier is the lowercased email, with@localappended to a bare username:DELETE FROM login_attempts WHERE identifier = 'fuzzball-admin@local';
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 useWithout --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>.
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:
- The Fuzzball UI URL that the
deployment-info-wait.shscript printed, when you first open the web UI. - 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"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: yesThe 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 adminassume-usertoken),fuzzball context showprints 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.
