Deploy a new ICOS Controller¶

The section provides all the necessary information to install and deploy the ICOS Controller in a Kubernetes cluster.

Hardware and Software Prerequisites¶

Since the ICOS Controller Suite consists of several modules that constitute the most important part of the system, the minimum hardware requirements are requested for a compatible host:

The installation furthermore requires full IP network connectivity between all machines that are part of the cluster (public or private network). For details on how to reach the required state of an installed Kubernetes distribution, the user can refer to the Kubernetes documentation.

Despite many distributions of Kubernetes, e.g. k3s, are compatible with ICOS, the current recommendation is limited to plain Kubernetes to host the controller suite with the following specifications:

• Kubernetes 1.19 or higher
• Kubectl
• Kustomize
• Clusteradm
• CSR Authentication support
• Orchestrator Control Plane
• Helm 3.7 (or newer versions).

Installation¶

The ICOS Controller Suite is distributed as an Helm chart. To install it, first create a yaml file that contains the configuration values. This creates the release and instantiates all the Kubernetes components associated with the ICOS Controller.

Before starting the installation, a set of OAuth clients needs to be created for some of the services in the controller to authenticate themselves. The following Oauth2 clients needs to be created:

In addition, a user in the IAM must be created for the shell backend.

The credentials for these clients needs to be speficied in the values file. At the moment, this is a manual operation, that will be automated by the on-boarding process in the future releases.

Create a values.yaml file with the following content:

global:
  controller:
    id: <unique-id-for-the-controller>
    url: <base-url-at-which-the>
    routing: host|port|path
    dpm:
      iamClientId: dynamic-policy-manager
      iamClientSecret: ********
    matchmaker:
      iamClientId: matchmaker
      iamClientSecret: ********
    securityCoordination:
      iamClientId: security-coordinator
      iamClientSecret: ********
    shellBackend:
      # the shell backend must use the lighthous client creeted when the ICOS Core has been installed
      iamClientId: lighthouse
      iamClientSecret: ********
      iamPassword: ********
      iamUser: ********
    telemetry:
      iamGrafanaClientId: telemetry-grafana
      iamGrafanaClientSecret: ********
  core:
    routing: host
    url: <url for the ICOS Core Suite>
    iam:
      publicKey: <IAM public Key>
      realm: icos-stable
    # only needed if the ICOS CA is enabled in the ICOS Core
    ca:
      bundle: <CA Root Certificate Bundle in Base64>

icos-ingress-controller:
  enabled: <true|false>

The url and routing values recur multiple times in the values file and can be confusing. They are used to simplify the configuration and derive autoamtically the ICOS services endpoints. A more detailed explaination can be found in the Developers Guide.

The icos-ingress-controller component should be enabled only if a) the agent is configured to use a host or path routing AND 2) if there are no other instances of the same component in the cluster. A more detailed exaplination can be found in the Developers Guide

After the values.yaml file has been created, deploy the Helm release with:

helm install --namespace icos-system --create-namespace contrl1 oci://harbor.res.eng.it/icos/helm/icos-controller --values values.yaml

oci://harbor.res.eng.it/icos-private/helm/icos-controller --values x.x.x-main.xxx

helm registry login harbor.res.eng.it/icos-private/helm and provide your credentials.

Main configuration values¶

Enable/Disable components¶

Single components that are part of the ICOS Controller can be enabled/disabled using the fowlloing values:

dynamic-policy-manager:
  enabled: false

shell-backend:
  enabled: false

aggregator:
  enabled: false

job-manager:
  enabled: false

job-manager-backend:
  enabled: false

telemetruum-hub:
  enabled: false

telemetruum-gateway:
  enabled: false

telemetruum-leaf:
  enabled: false

security-coordination-module:
  enabled: false

security-lomos-api2:
  enabled: false

intelligence-coordination:
  enabled: false

matchmaker:
  enabled: false

dataclay:
  enabled: false

Persitence¶

By default, persistence is enabled and the components that needs to persist data will create a PersistentVolumeClaim. To control how the persistence is configured or disable it, use the following values (in the example provided, persistence is disabled for all components):

job-manager-backend:
  primary:
    persistence:
      enabled: false

dynamic-policy-manager:
  mongodb:
    persistence:
      enabled: false

telemetruum-hub:
  grafana:
    persistence:
      enabled: false
  opensearch:
    master:
      persistence:
        enabled: false
  thanos:
    compactor:
      persistence:
        enabled: false
    receive:
      persistence:
        enabled: false

Exposure¶

At the moment, by default, all services are created as ClusterIP and, therefore, the Controller is not accessible from outside its cluster (this is going to change in the next version).

To expose the controller using NodePort services, use the following values:

global:
  icos:
    shellBackend:
      externalPort: 32500

job-manager:
  service:
    nodePort: 32300
    type: NodePort

shell-backend:
  service:
    nodePort: 32500
    type: NodePort

telemetruum-hub:
  otel-collector:
    service:
      ports:
        otlp:
          nodePort: 32103
      type: NodePort

Uninstall Chart¶

This removes all the Kubernetes components associated with the ICOS Controller and deletes the release.

helm show values icos-controller

You may similarly use the above configuration commands on each chart dependency to see its configurations.

helm uninstall [RELEASE_NAME]

See helm uninstall for command documentation.