Deploy the ICOS Core¶

The ICOS Core Suite deploys the three services needed to bootstrap a new ICOS Continuum: - the ICOS CA: responsible for issuing TLS certificates to all continuum services, - the ICOS Identity and Access Management (IAM) service: used to authenticate and authorize requests and users in the continuum, - the ICOS Lightouse: used to register ICOS Controllers to the system.

The ICOS Core Suite is an Helm chart that deploys and configures the three components.

The installation of a new ICOS Core is done in two steps because some configuration parameters are generated during the deployment itself. In particuar, in the first step the CA's Root Certificate is generated and in the second step the component (the certificates issuer) needs to be configured with the CA root certificate and password which are generated at the first run of the ICOS CA.

Step 1¶

In this step, the ICOS Core Suite is installed using Helm, but some components will be disabled and left configured and will be installed during the second step.

Create a values.yaml file to sepficy how to expose the ICOS Core services (for an in-depth guide see the Services Exposure section):

global:
  core:
    url: https://core.icos-stable.10-160-3-236.sslip.io/
    routing: host

The default values, will also create two Kubernetes Persistent Volumes to store IAM db and CA db. They can be disabled using the Helm values.

Now, run the installation command with:

helm install --namespace icos-core --create-namespace core1 oci://harbor.res.eng.it/icos/helm/icos-core --values values.yaml --set icos-ingress-controller.step-issuer.enabled=false

This will perform the installation keepling the issuer component disabled. It will be configured and enabled in the second step.

Step 2¶

Initialize the IAM Service¶

After the keycloak pod is ready, it is possible to access the Keycloak Web Administration Console to the configured URL (will depend on the url and routing Helm values chosen for the installation).

The default admin user for keycloak is icos-admin.

The default password for the admin user is autogenerated and can be retrieved with the following command:

kubectl get secret -n icos-core core1-iam-passwords -o jsonpath="{.data.admin-password}" | base64 -d

After the login:

1. Create a new realm for the ICOS Continuum (e.g. "my-icos-continuum")
2. Create a new Client named lighthouse with "Client Authentication" and "Authorization" capabilities enabled.

Take note of the clientSecret generated.

Collect CA certificates and secrets¶

Before proceeding, take note of some CA generated values:

• ca bundle:

  kubectl exec --namespace icos-core core1-step-certificates-0 -- sh -c "step ca root | step base64"
  

• ca issuer kid

  kubectl get configmap --namespace icos-core core1-step-certificates-config -o jsonpath="{.data['ca\.json']}" | jq .authority.provisioners[0].key.kid
  

• ca issuer password

  kubectl get secret --namespace icos-core core1-step-certificates-provisioner-password -o jsonpath='{.data.password}' | base64 --decode
  

Re-run Helm installation¶

Edit the values.yaml file and add the values collected in the previous steps:

global:
  core:
    url: https://core.icos-stable.10-160-3-236.sslip.io/
    routing: host
    ca:
      bundle: <value for the "ca bundle" retrieved in previous steps>
      issuerKid: <value for the "ca issuer kid" retrieved in previous steps>
      issuerPassword: <value for the "ca issuer password" retrieved in previous steps>
    iam:
      realm: <name of the Keycloak realm created in the previous step>
    lighthouse:
      iamClientSecret: <value of the client secret for the Keycloak's "lighthouse" client created in the previous step>

# needed if routing is "host" or "path" and no other instances of the "icos-ingress-controller" are already installed in the cluster
icos-ingress-controller:
  enabled: true

Re-run the helm install command (with issuer enabled):

helm upgrade --namespace icos-core core1 oci://harbor.res.eng.it/icos/helm/icos-core --values values.yaml

Force the re-creation of the step-issuer and lightouse pods:

kubectl delete pod --namespace icos-core -l "app.kubernetes.io/name=step-issuer"
kubectl delete pod --namespace icos-core -l "app.kubernetes.io/name=icos-lighthouse"

Verify¶

If the installation is successful, the following pods should be running and in Ready status:

❯ kubectl get pods -n icos-core
NAME                                                              READY   STATUS    RESTARTS   AGE
core1-cert-manager-cainjector-6bcd4d946-wr9kv                     1/1     Running   0          24h
core1-cert-manager-controller-6d8fffd985-927bw                    1/1     Running   0          24h
core1-cert-manager-webhook-584654d5-c4kxp                         1/1     Running   0          24h
core1-icos-lighthouse-b7b44b6dc-6jn2b                             1/1     Running   0          20h
core1-keycloak-0                                                  1/1     Running   0          24h
core1-nginx-ingress-controller-default-backend-5cd59c4c4b-khfmj   1/1     Running   0          24h
core1-nginx-ingress-controller-fddbd549-m87ss                     1/1     Running   0          24h
core1-postgresql-0                                                1/1     Running   0          24h
core1-step-certificates-0                                         1/1     Running   0          24h
core1-step-issuer-67578656cd-94tx2                                2/2     Running   0          24h

If the installation is working properly, after few minutes the following three certificates should have been created and in status Ready:

❯ kubectl get certificate -n icos-core
NAME                           READY   SECRET                         AGE
core1-ca-ingress-tls           True    core1-ca-ingress-tls           24h
core1-iam-ingress-tls          True    core1-iam-ingress-tls          24h
core1-lighthouse-ingress-tls   True    core1-lighthouse-ingress-tls   24h