Kamiwaza 0.11.0 Installation Guide

This guide covers a fresh Kamiwaza production install on a RHEL9 host using the packed prod RPM, offline wrap bundle, and install-prod.sh.

Scope

This guide assumes:

• a fresh RHEL9 host
• release artifacts have already been built
• you are installing from the packaged offline artifacts, not from live repos
• install-prod.sh is the entrypoint

Inputs You Need

Before you start, decide these values:

• DOMAIN: external hostname for the install, for example kamiwaza.example.com
• ADMIN_PASSWORD: initial admin password
• release artifact location:
  • local directory, or
  • s3://<bucket>/<prefix>/
• offline image tags:
  • app/core/init-users tag
  • frontend tag
  • chainguard base/containers tag

Required Artifacts

You need these files from the offline release:

• kamiwaza-prod-*.x86_64.rpm
• kamiwaza-helm.*.tar
• kamiwaza-helm.sha256
• kamiwaza-helm.asc
• kamiwaza-tools-rpm.pub.gpg

Host Prerequisites

You need:

• sudo access on the RHEL9 host
• aws CLI only if you are pulling artifacts from S3

Step 1: Set Operator Variables

Fill in the variables for your release:

DOMAIN="kamiwaza.example.com"
ADMIN_PASSWORD="replace-me"
RELEASE_DIR="$HOME/kajiya-release"
APP_TAG="release-0.11.0"
FRONTEND_TAG="${APP_TAG}"
CONTAINERS_TAG="${APP_TAG}"

Step 2: Retrieve Release Artifacts

If the release artifacts are already on disk, skip to Step 3.

Example S3 pull:

BUCKET="kajiya"
PREFIX="builds/offline/<timestamp_folder>"
mkdir -p "${RELEASE_DIR}"
cd "${RELEASE_DIR}"
aws s3 cp --recursive "s3://${BUCKET}/${PREFIX}/" .

Step 3: Verify the Required Files Are Present

cd "${RELEASE_DIR}"
ls -1 \
  kamiwaza-prod-*.x86_64.rpm \
  kamiwaza-helm.*.tar \
  kamiwaza-helm.sha256 \
  kamiwaza-helm.asc \
  kamiwaza-tools-rpm.pub.gpg

Step 4: Install the Prod RPM

sudo dnf install -y perl
sudo rpm -Uvh --replacepkgs ./kamiwaza-prod-*.x86_64.rpm

Step 5: Stage the Wrap Bundle Files

sudo mkdir -p /opt/kamiwaza/prereqs
sudo cp ./kamiwaza-helm.*.tar ./kamiwaza-helm.sha256 ./kamiwaza-helm.asc \
  ./kamiwaza-tools-rpm.pub.gpg /opt/kamiwaza/prereqs/

Step 6: Install Host Prerequisites

sudo /opt/kamiwaza/scripts/bootstrap-prereqs.sh \
  --embedded-root /opt/kamiwaza/prereqs \
  --os rhel
export HELM_PLUGINS="/usr/local/share/helm/plugins"

Sanity check the required tools:

ansible-playbook --version | head -n1
podman --version
kubectl version --client
helm version
helmfile version
helm dt version

Step 7: Create the Optional Site Overrides File

Most installs can skip this step. Create the file only if you need non-default settings such as security banners, consent, ReBAC, or a non-prod template catalog stage.

Use this operator-facing path:

/opt/kamiwaza/cluster/values/overrides.yaml

Example:

sudo tee /opt/kamiwaza/cluster/values/overrides.yaml > /dev/null <<'EOF'
core:
  security:
    consent:
      enabled: true
    banner:
      enabled: true
      topText: "UNCLASSIFIED//TEST SYSTEM"
      topColor: "#00A651"
      bottomText: "UNCLASSIFIED//TEST SYSTEM"
      bottomColor: "#00A651"
  scheduler:
    extraEnv:
      - name: LICENSE_KEY
        value: "replace-with-license-key"
      - name: AUTH_REBAC_ENABLED
        value: "true"
      - name: AUTH_REBAC_BACKEND
        value: "postgres"
      - name: AUTH_REBAC_ALLOW_COMMUNITY_FALLBACK
        value: "true"
EOF

Step 8: Export Offline Image Tags

Set the tags for the release you are installing:

export KAMIWAZA_VERSION="${APP_TAG}"
export KAMIWAZA_IMAGE_TAG="${APP_TAG}"
export KAMIWAZA_OFFLINE_APP_IMAGE_TAG="${APP_TAG}"
export KAMIWAZA_OFFLINE_INIT_KEYCLOAK_USERS_TAG="${APP_TAG}"
export KAMIWAZA_OFFLINE_CORE_TAG="${APP_TAG}"
export KAMIWAZA_OFFLINE_FRONTEND_TAG="${FRONTEND_TAG}"
export KAMIWAZA_OFFLINE_CHAINGUARD_BASE_TAG="${CONTAINERS_TAG}"

Step 9: Run the Offline Install

sudo -E /opt/kamiwaza/scripts/install-prod.sh \
  --offline \
  --skip-prereq-bootstrap \
  --domain "${DOMAIN}" \
  --admin-password "${ADMIN_PASSWORD}" \
  --wrap-bundle '/opt/kamiwaza/prereqs/kamiwaza-helm.*.tar' \
  --wrap-sha256 /opt/kamiwaza/prereqs/kamiwaza-helm.sha256 \
  --wrap-signature /opt/kamiwaza/prereqs/kamiwaza-helm.asc \
  --wrap-pubkey /opt/kamiwaza/prereqs/kamiwaza-tools-rpm.pub.gpg \
  -e helm_timeout=12m \
  -y

Step 10: Verify the Install

kubectl get pods -n kamiwaza
kubectl -n kamiwaza get secret kamiwaza-user-admin \
  -o jsonpath="{.data.password}" | base64 -d; echo
curl -kI "https://${DOMAIN}"

How Configuration Is Supplied

For this install path, configuration comes from three places:

1. --domain
2. --admin-password
3. the exported KAMIWAZA_OFFLINE_* tag vars plus /opt/kamiwaza/cluster/values/overrides.yaml

Troubleshooting

aws: command not found

Install AWS CLI or skip the S3 download step and stage the release artifacts locally.

no wrap chunk files matched glob

Keep the --wrap-bundle argument quoted:

--wrap-bundle '/opt/kamiwaza/prereqs/kamiwaza-helm.*.tar'

ReBAC session startup failure

If you enable AUTH_REBAC_SESSION_ENABLED="true", you must also provide AUTH_REBAC_SESSION_REDIS_URL.

Embedded prereq payload missing

If /opt/kamiwaza/prereqs/rpms/ is missing after RPM install, verify that you installed the correct packaged prod RPM for the offline release.