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. At the moment, this is a manual operation, that will be automated by the on-boarding process in the future releases.

At the moment the Helm chart requires the following mandatory values to be set:

global:
  external:
    host: <controller public ip>
  icos:
    controllerId: <controller unique name>
    iam:
      publicKey: <IAM Public Key>
      realm: <IAM Realm>
      baseUrl: <IAM URL>
    lighthouse:
      baseUrl: <Light House Endpoint>
    jobManager:
      dbPassword: <a password for the Job Manager Database>
    matchmaker:
      iamClientId: <IAM client id used by the matchmaker>
      iamClientSecret: <secret of the matchmaker client>
    shellBackend:
      iamClientId: <IAM client id used by the Shell Backend>
      iamClientSecret: <secret of the shell backemd client>
      iamUser: <a IAM user used by the Shell Backend to authenticate>
      iamPassword: <password of the Shell Backend user>
    telemetry:
      iamGrafanaClientId: <IAM client is used by the Grafana service>
      iamGrafanaClientSecret: <password of the Grafana client>

Then deploy the Helm release with:

helm install contrl1 oci://harbor.res.eng.it/icos/helm/icos-controller --values my-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 uninstall [RELEASE_NAME]

Configuration¶

See Customizing the Chart Before Installing. To see all configurable options with detailed comments, visit the chart's values.yaml, or run these configuration commands:

helm show values icos-controller

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