Installation on Google Cloud Platform via GKE

Overview

This guide covers the installation of CAST Imaging on Google Cloud Platform Google Kubernetes Engine  (GKE) using Helm charts.

Requirements

• Access to Docker Hub registry - CAST Imaging Docker images are available as listed in the table below
• A clone of the latest release branch from the Git repository containing the Helm chart scripts: git clone https://github.com/CAST-Extend/com.castsoftware.castimaging-v3.kubernetessetup (to clone an older release, add the “-b x.x.x” flag with the desired release number).
• A valid CAST Imaging License

Docker images

CAST Imaging is provided in a set of Docker images as follows:

Installation process

Before starting the installation, ensure that your Kubernetes cluster is running, all the CAST Imaging docker images are available in the registry and that helm and kubectl are installed on your system.

Step 1 - GKE environment setup

• Create your GKE environment, see GKE - Cluster Setup. Also refer to the Google documentation 
• Retrieve the cluster credentials using GCP CLI:

gcloud container clusters get-credentials my-cluster --zone=my-zone

• Install kubectl - see https://kubernetes.io/docs/tasks/tools/ 
• Install helm:
  • Binary download: https://github.com/helm/helm/releases 
  • Documentation: https://helm.sh/docs/intro/quickstart/ 

Step 2 - Prepare and run the CAST Imaging installation

• Review and adjust the parameter values in the values.yaml file (located at the root of the cloned Git repository branch) in between the section separated with # marks.
• Ensure you set the K8SProvider: option to GKE
• Run helm-install.bat|sh (depending on your base OS) located at the root of the cloned Git repository branch

Keycloak component parameters

CAST Imaging uses the Keycloak system to manage all authentication requirements (see Authentication for more information). You should take note of two parameters that you may wish to customize before running the installation:

KeycloakAdminPassword: <default-password>
KCADMIN_USERNAME: kcadmin

• KeycloakAdminPassword defines the password for the Keycloak admin “service” account used for intra-component communication. By default this password is set to “admin” (encrypted in base64). Update this if you wish to change this password e.g. by running echo -n "my-new-password" | base64 to generate a new encrypted password. This password can also be updated post install (see below).

• KCADMIN_USERNAME defines the name of the account (kcadmin by default with password “admin”) used to login in to the Keycloak UI to administer authentication. Update kcadmin to your preferred account name. Note that this change can only be done BEFORE a new installation.

Step 3 - Configure network settings for console-gateway (main entrypoint) and extendproxy (optional) services

To access those services from outside, you will need to setup a reverse proxy such as an Ingress Service.

Choose one of the three options below (Gateway API, NGINX Ingress, or Istio). All three options share a common Final steps subsection at the end.

Option A: If you want to use a Gateway API implementation

The Gateway API  is the modern, vendor-neutral successor to the Kubernetes Ingress API. CAST Imaging provides a GatewayAPI.yaml template that creates the Gateway and HTTPRoute resources needed to expose console-gateway-service and (optionally) extendproxy. The template has been tested with NGINX Gateway Fabric  (NGF), but the Gateway / HTTPRoute resources are portable to any conformant implementation (Istio, Envoy Gateway, etc.).

• Set UseGatewayAPI: true in values.yaml:

UseGatewayAPI: true

• Install the Gateway API CRDs on the cluster (if not already installed):

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.1/standard-install.yaml

• Install a Gateway controller. For NGINX Gateway Fabric:

helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway

Verify the installation:

kubectl get gatewayclass
kubectl get pods -n nginx-gateway

• Configure the Gateway resource in values.yaml. Two options are supported:

  • Option 1 - Create a new Gateway dedicated to CAST Imaging (default):

  Gateway:
    create: true
    className: nginx     # Use "nginx" for NGF, or the gatewayClassName of your controller
  

  • Option 2 - Attach to an existing shared Gateway already deployed on the cluster:

  Gateway:
    create: false
    name: my-shared-gateway
    namespace: my-gateway-namespace
  

  When attaching to an existing Gateway, it must already define listeners named https (and https-extend if ExtendProxy.enable is true with a different hostname for the extend proxy). The shared Gateway’s listener must also allow routes from the CAST Imaging namespace (allowedRoutes.namespaces.from: All or a matching Selector).

• Create TLS Secret(s) using the certificate files associated to the DNS name(s) you are planning to use. The secrets must be created in the CAST Imaging namespace (Gateway listeners read certificates from the Gateway’s own namespace, unless a ReferenceGrant is used):

kubectl create secret tls tls-secret-cast --cert=my-cert-folder\myhostname.com\fullchain.pem --key=my-cert-folder\myhostname.com\privkey.pem -n castimaging-v3
# Optional (only needed if you are deploying ExtendProxy):
kubectl create secret tls tls-secret-cast-extend --cert=my-cert-folder\myextendhostname.com\fullchain.pem --key=my-cert-folder\myextendhostname.com\privkey.pem -n castimaging-v3
# (fullchain.pem <=> tls.crt ; privkey.pem <=> tls.key)

If you are deploying ExtendProxy (optional) and want to use the same hostname for both services, just create the 2 secrets using the same certificate files.

➡️ Continue with the Final steps (Gateway API, Istio or NGINX Ingress) subsection below.

Option B: If you want to use a Kubernetes NGINX Ingress

• Set CreateIngress: true in values.yaml:

CreateIngress: true

• Install the Ingress driver on the cluster:

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update        
helm install ingress-nginx ingress-nginx/ingress-nginx --namespace ingress-nginx --create-namespace --set controller.ingressClassResource.controllerValue="k8s.io/ingress-nginx"

• Create TLS Secret(s) using the certificate files associated to the DNS name(s) you are planning to use:

kubectl create secret tls tls-secret-cast --cert=my-cert-folder\myhostname.com\fullchain.pem --key=my-cert-folder\myhostname.com\privkey.pem -n castimaging-v3
# Optional (only needed if you are deploying ExtendProxy):
kubectl create secret tls tls-secret-cast-extend --cert=my-cert-folder\myextendhostname.com\fullchain.pem --key=my-cert-folder\myextendhostname.com\privkey.pem -n castimaging-v3
# (fullchain.pem <=> tls.crt ; privkey.pem <=> tls.key)

If you want to use the same hostname for both services, just create the 2 secrets using the same certificate files.

➡️ Continue with the Final steps (Gateway API, Istio or NGINX Ingress) subsection below.

Option C: If you want to use an Istio Ingress Gateway

• Set CreateIstioGateway: true in values.yaml:

CreateIstioGateway: true

Note that Istio may be already installed on your cluster. Please check with your administrator.

• Install Istio on the cluster (Linux/Mac):

curl -L https://istio.io/downloadIstio | sh -
cd istio-*
export PATH=$PWD/bin:$PATH
istioctl install --set profile=default -y

• Install Istio on the cluster (Windows - PowerShell using Chocolatey):

choco install istioctl
istioctl install --set profile=default -y

• Install Istio on the cluster (Windows - PowerShell using manual download and install of a specific version)

$ISTIO_VERSION="1.28.4"  # Check https://github.com/istio/istio/releases for latest
Invoke-WebRequest -Uri "https://github.com/istio/istio/releases/download/$ISTIO_VERSION/istio-$ISTIO_VERSION-win.zip" -OutFile "istio.zip"
Expand-Archive -Path "istio.zip" -DestinationPath "." -Force
cd "istio-$ISTIO_VERSION"
$env:PATH = "$PWD\bin;$env:PATH"
istioctl install --set profile=default -y

• Optional - If you want to use a specific Istio Gateway already deployed on your cluster, set the gateway name in ExistingIstioGatewayName:

UseIstioGateway: true
ExistingIstioGatewayName: "some-namespace/my-gateway"

• Create TLS Secret(s) using the certificate files associated to the DNS name(s) you are planning to use (to be created in the istio-system namespace):

kubectl create secret tls tls-secret-cast --cert=my-cert-folder\myhostname.com\fullchain.pem --key=my-cert-folder\myhostname.com\privkey.pem -n istio-system
# Optional (only needed if you are deploying ExtendProxy):
kubectl create secret tls tls-secret-cast-extend --cert=my-cert-folder\myextendhostname.com\fullchain.pem --key=my-cert-folder\myextendhostname.com\privkey.pem -n istio-system
# (fullchain.pem <=> tls.crt ; privkey.pem <=> tls.key)

If you want to use the same hostname for both services, just create the 2 secrets using the same certificate files.

➡️ Continue with the Final steps (Gateway API, Istio or NGINX Ingress) subsection below.

Final steps (Gateway API, Istio or NGINX Ingress)

Optional - When Gateway API, Istio or NGINX Ingress is implemented to access the console-gateway service with a certificate that cannot be verified (e.g., self-signed certificate or internal CA), the certificate will need to be stored in CAST auth-service to avoid certificate validation errors:

• set: UseCustomTrustStore: true in values.yaml
• Insert the encoded certificate:
  • directly inside the auth.caCertificate variable in values.yaml
  • or using helm upgrade ... --set-file auth.caCertificate=ca.crt ... to override the variable value with the ca.crt file content

UseCustomTrustStore: true
auth:
  caCertificate: |
    -----BEGIN CERTIFICATE-----
    XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
    XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
    XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
    -----END CERTIFICATE-----

If you are also deploying ExtendProxy (optional), choose one of the two sub-options below:

• Set hostnames in values.yaml - same-hostname-option: use the same hostname for all services

FrontEndHost: https://myhostname.com 
ExtendProxy
  enable: true
  exthostname: myhostname.com

Exposed URLs will be:

• https://myhostname.com (or https://myhostname.com/mycontext if ContextUrl is enabled)

• https://myhostname.com/extendproxy

• Set hostnames in values.yaml - different-hostname-option: use a different hostname for each service:

FrontEndHost: https://myhostname.com 
ExtendProxy
  enable: true
  exthostname: myextendhostname.com

Exposed URLs will be:

• https://myhostname.com (or https://myhostname.com/mycontext if ContextUrl is enabled)

• https://myextendhostname.com/extendproxy

• Apply the helm chart changes by running helm-upgrade.bat|sh (depending on your base OS) located at the root of the cloned Git repository branch.

• Create a DNS record pointing at the reverse proxy external IP address. To retrieve the external IP:

# For NGINX Gateway Fabric, use this command:
kubectl get svc -n nginx-gateway
#
# For an NGINX Ingress, use this command:
kubectl get ingress -n castimaging-v3
#
# For an Istio Ingress, use this command:
kubectl get service istio-ingressgateway -n istio-system

Step 4 - Install Extend Local Server (optional)

To install Extend Local Server:

• In values.yaml (located at the root of the cloned Git repository branch), set ExtendProxy.enable to true and update the ExtendProxy.exthostname variable with the DNS name. In case you want to access it thru its Load Balancer (set “CreateLoadBalancer: true”), use the LoadBalancer external IP address instead or the DNS name (kubectl get service -n castimaging-v3 extendproxy to get the IP):

ExtendProxy:
    enable: true
    exthostname:  myextendhost.com # or LoadBalancer external IP address

• Run helm-upgrade.bat|sh (depending on your base OS) located at the root of the cloned Git repository branch.
• Review the log of the extendproxy pod to find the Extend Local Server administration URL and API key (these are required for managing Extend Local Server and configuring CAST Imaging to use it - you can find out more about this in Extend Local Server). You can get the extendproxy pod name by running kubectl get pods -n castimaging-v3 then run kubectl logs -n castimaging-v3 castextend-xxxxxxxx to display the log.
• In Console System Settings, use this value for the “CAST Extend URL”: http://extendproxy:8085

Step 5 - Initial start up configuration

License and Extend API key steps can be skipped if values were provided for these helm chart variables:

• ImagingLicenseType
• ImagingLicense
• ExtendApiKey

If not, when the install is complete, browse to the public/external URL and login using the default local admin/admin credentials. You will be prompted to configure:

• your licensing strategy. Choose either a Named Application strategy (where each application you onboard requires a dedicated license key entered when you perform the onboarding), or a Contributing Developers strategy (a global license key based on the number of users):

• CAST Extend settings / Proxy settings (if you chose to install Extend Local Server (see Step 4 above) then you now need to input the URL and API key so that CAST Imaging uses it).

As a final check, browse to the URL below and ensure that you have at least one CAST Imaging Node Service, the CAST Dashboards and the CAST Imaging Viewer components listed:

https://<public or external URL>/admin/services

Step 6 - Configure authentication

Out-of-the-box, CAST Imaging is configured to use Local Authentication via a simple username/password system managed by Keycloak. Default login credentials for CAST Imaging are provided (admin/admin) with the global ADMIN profile so that installation can be set up initially.

CAST recommends configuring CAST Imaging (via the Keycloak component) to use your on-premises enterprise authentication system such as LDAP or SAML Single Sign-on instead before you start to onboard applications. To access the Keycloak UI to configure your authentication system, use the kcadmin account. See Authentication for more information.

Updating the Keycloak default password

Out-of-the-box Keycloak is provisioned with a service account used for intra-component communication with the credentials admin/admin. If you need to change this password post-installation, follow the steps below:

Change the password via the UI

1. Navigate to the Keycloak account security page using the following URL (replace <public-external-url> with your installation’s external URL):

https://<public-external-url>/auth/realms/master/account/account-security/signing-in

2. Log in with the default credentials (admin/admin)
3. Update the password through the account settings interface

Update the password in the Helm Chart

After changing the password in the Keycloak UI, you must update the Helm chart configuration to match.

1. Encode your new password in base64 format. On a Linux machine, run:

echo -n "my-new-password" | base64

2. In your cloned Git repository containing the CAST Imaging Kubernetes installation files, open:

values.yaml

3. Locate this line:

KeycloakAdminPassword: <default-password>

4. Replace the defined password with your base64-encoded password:

KeycloakAdminPassword: <your-base64-encoded-password>

5. Example: If your base64 output is bXktbmV3LXBhc3N3b3Jk, the line should read:

KeycloakAdminPassword: bXktbmV3LXBhc3N3b3Jk

Apply changes

Run Util-ScaleDownAll.bat and helm-upgrade.bat to restart CAST Imaging and apply the changes.

How to start and stop CAST Imaging

Use the following script files (located at the root of the cloned Git repository branch) to stop and start CAST Imaging:

• Util-ScaleDownAll.bat|sh
• Util-ScaleUpAll.bat|sh

Optional setup choices

Use an external PostgreSQL instance

If you do not want use the PostgreSQL instance preconfigured in this helm chart, you can disable it and configure a Cloud SQL for PostgreSQL database instead.

• Setup your Cloud SQL for PostgreSQL database

  • PostgreSQL 15 - 8GB RAM minimum recommended
  • Define a superuser authentified by password

• In values.yaml:

  • Set CastStorageService.enable to false (will disable the embedded PostgreSQL installation)
  • Set CustomPostgres.enable to true
  • Set CustomPostgres.host and CustomPostgres.port to match your custom database host name and port number
  • Set CustomPostgres.adminlogin and PostgresDbPassword to match the superuser login name and password of your custom database

• Proceed with the CAST Imaging installation described above

Kubernetes storage location information

For information about storage locations used across the containers in a CAST Imaging Kubernetes deployment (for example persistent volumes, ConfigMap-backed configuration files, Secrets, and ephemeral (in-memory) volumes), see Kubernetes storage location information.