Keycloak Package Chart Maintenance

This guide covers updating, testing and maintaining the Big Bang Keycloak package.

Overview

Big Bang’s Keycloak implementation:

• Wraps the upstream codecentric keycloakx chart
• Bundles bitnami postgres as a dependency
• Includes the custom p1-auth-plugin for DoD-specific auth requirements

Update Process

1. Research: Review Keycloak release notes for breaking changes

2. Update Dependencies:

   helm dependency update ./chart
   

3. Update Chart Files:

4. Chart.yaml: Update version numbers and annotations

   name: keycloak
   version: XX.X.X-bb.X
   appVersion: XX.X.X
   dependencies:
     - name: postgresql
       version: 16.6.7
       repository: oci://registry-1.docker.io/bitnamicharts
       condition: postgresql.enabled
     - name: gluon
       version: "X.X.X"
   # Update annotations section accordingly
   

5. CHANGELOG.md: Document changes

6. README.md: Update using gluon library script

7. Plugin Management:

8. Build/publish the p1-auth-plugin (use test label initially)
9. After testing, create an official release tag

10. Publish to IronBank following these instructions

11. Testing: Test both clean install and upgrade scenarios

12. BigBang MR: Update with new plugin init-container tag

Testing Environment Setup

Prerequisites

# Set credentials (can be added to ~/.bashrc)
export REGISTRY_USERNAME='<your_username>'
export REGISTRY_PASSWORD='<your_password>'

# Path to BigBang repo (no trailing slash)
export BIGBANG_REPO_DIR=~/repos/bigbang

Cluster Setup

1. Create dev cluster:

   "${BIGBANG_REPO_DIR}"/docs/assets/scripts/developer/k3d-dev.sh -a
   

2. Configure kubectl:

   export KUBECONFIG=~/.kube/<your_kubeconfig_file>
   

3. Deploy Flux:

   "${BIGBANG_REPO_DIR}"/scripts/install_flux.sh -u "${REGISTRY_USERNAME}" -p "${REGISTRY_PASSWORD}"
   

Deploy BigBang

helm upgrade -i bigbang ${BIGBANG_REPO_DIR}/chart \
  -n bigbang \
  --create-namespace \
  --set registryCredentials.username=${REGISTRY_USERNAME} \
  --set registryCredentials.password=${REGISTRY_PASSWORD} \
  -f https://repo1.dso.mil/big-bang/bigbang/-/raw/master/tests/test-values.yaml \
  -f https://repo1.dso.mil/big-bang/bigbang/-/raw/master/chart/ingress-certs.yaml \
  -f docs/dev-overrides/enable-sso.yaml

This deploys Keycloak, Authservice, Istio stack, and several applications with SSO enabled.

Configuration

Override File Options

1. Branch/Tag Testing:

   addons:
     keycloak:
       git:
         tag: null
         branch: "renovate/ironbank" # Example branch
   

2. Plugin Image:

   addons:
     keycloak:
       values:
         upstream:
           extraInitContainers: |-
             - name: plugin
               image: registry1.dso.mil/ironbank/big-bang/p1-keycloak-plugin:3.5.7
   

   Alternatively, you can modify enable-sso.yaml to specify the plugin you’re testing.

3. SSO SAML Metadata:

   sso:
     saml:
       # curl -fsSL https://keycloak.dev.bigbang.mil/auth/realms/baby-yoda/protocol/saml/descriptor for this
       metadata: ""
   

Test Cases

1. Admin Console: https://keycloak.dev.bigbang.mil/auth/admin/ (admin/password)

2. User Management:

3. Create test users (CAC and non-CAC)
4. For non-CAC: use incognito window or disconnect CAC reader
5. Set email as verified via admin console

6. Note: A cypress user is created automatically in test deployments

7. SSO Integration:

8. Test with Grafana (https://grafana.dev.bigbang.mil)
9. Test with Mattermost (https://chat.dev.bigbang.mil)

10. Test with Sonarqube (https://sonarqube.dev.bigbang.mil)

11. Custom Forms:

12. Account: https://keycloak.dev.bigbang.mil/auth/realms/baby-yoda/account/
13. Password: https://keycloak.dev.bigbang.mil/auth/realms/baby-yoda/account/password
14. TOTP: https://keycloak.dev.bigbang.mil/auth/realms/baby-yoda/account/totp

15. Registration: https://keycloak.dev.bigbang.mil/register

16. Integration Testing: Follow Big Bang testing guide