2. Deploy the orchestrator

The orchestrator is a standalone service that exposes a gRPC (over HTTP) API.

It can be deployed anywhere as long as the backends can connect to it. Putting it on the same cluster as one of the backends is safe, as it does not use much resources. Therefore are deploying it on cluster 1

Warning

The orchestrator is the ultimate source of truth and traceability in Substra.

This means that, in a “real” scenario, it should be hosted by an organization trusted by all others, because it is where a bad actor could cause the most issues.

2.1. Prepare your Helm values

See also

Full reference on Artifact Hub.

1. Create a Helm values file named orchestrator-values.yaml with the following content:

   ingress:
     enabled: true
     hostname: orchestrator.cluster-1.DOMAIN
   

   This sets up the ingress to make your orchestrator accessible at the defined hostname.

1. Setup your Substra channels. In the orchestrator-values.yaml file, add the following content:

   channels:
     - name: our-channel
       organizations: [ingen, biotechnica]
   

   This creates one channel with two organizations, named ingen and biotechnica.

The next section improves security and is mandatory for true production deployments that communicate over unsecured networks. But, for test deployments or secured networks, you can skip to Deploy the Chart.

2.2. Setup TLS

In a production environment, we recommend to enable TLS for your orchestrator. For this, you will need to generate a few certificates. Here we will generate them manually but you can also use automated tools for this task. If you want to use automated tools we provide a certificate resource for cert-manager. The orchestrator.tls.createCertificates values should be a good place for you to get started.

The orchestrator needs to handle SSL termination for this to work. You may need to adapt your proxy configuration to let the traffic go through it. For example if you use ingress-nginx you may want to read the ssl passthrough chapter of their documentation.

To setup TLS, follow these steps:

1. Enable TLS, in the orchestrator-values.yaml file add the following content:

   orchestrator:
     tls:
       enabled: true
   

2. Generate a self-signed Certificate Authority:

   1. Create an openssl config file named example-openssl.cnf with the following content:

      [ req ]
      default_bits           = 2048
      default_md             = sha256
      distinguished_name     = req_distinguished_name
      
      [ req_distinguished_name ]
      
      [ v3_ca ]
      basicConstraints = critical,CA:TRUE
      subjectKeyIdentifier = hash
      authorityKeyIdentifier = keyid:always,issuer:always
      keyUsage = cRLSign, keyCertSign
      

   2. Generate a private key for signing certificates:

      openssl genrsa -out orchestrator-ca.key 2048
      

   1. Generate your Certificate Authority certificate:

      openssl req -new -x509 -days 365 -sha256 -key orchestrator-ca.key -extensions v3_ca -config example-openssl.cnf -subj "/CN=Orchestrator Root CA" -out orchestrator-ca.crt
      

3. Generate a certificate for the orchestrator

   1. Generate a certificate signing request:

      openssl req -newkey rsa:2048 -nodes -keyout orchestrator-tls.key -subj "/CN=orchestrator.cluster-1.DOMAIN" -out orchestrator-cert.csr
      

      This will generate a private key for the orchestrator and a certificate signing request. You should have two new files in your current directory orchestrator-tls.key and orchestrator-cert.csr.

   2. Sign the request with the Certificate Authority key:

      openssl x509 -req -days 365 -in orchestrator-cert.csr -CA orchestrator-ca.crt -CAkey orchestrator-ca.key -CAcreateserial -out orchestrator-tls.crt -sha256 -extfile <(printf "subjectAltName=DNS:orchestrator.cluster-1.DOMAIN")
      

      Caution

      We don’t recommend having your certificate valid for a year, you should change this value based on your company policy.

   3. Delete the Certificate Signing Request:

      rm orchestrator-cert.csr orchestrator-ca.srl
      

4. Create a Kubernetes ConfigMap for the CA certificate:

   kubectl create configmap orchestrator-tls-cacert --from-file=ca.crt=orchestrator-ca.crt
   

5. Create a Kubernetes Secret for the orchestrator TLS key and certificate:

   kubectl create secret tls orchestrator-tls-server-pair --cert=orchestrator-tls.crt --key=orchestrator-tls.key
   

6. Optional: If you also want to setup mTLS to authenticate your client follow the guide Set up mutual TLS.

2.3. Deploy the Chart

To deploy the orchestrator in your Kubernetes cluster follow these steps:

1. Deploy the orchestrator Helm chart:

   helm install orchestrator substra/orchestrator --values orchestrator-values.yaml --namespace orchestrator --create-namespace
   

   Replace VERSION with the version of the orchestrator helm chart you want to deploy.

2. Validate that the deployment was successful:

   grpcurl [--cacert orchestrator-ca.crt] orchestrator.cluster-1.DOMAIN:PORT list
   

   Add the --cacert argument if you deployed your orchestrator with TLS.

   PORT should be 443 if TLS is enabled, else 80.

   The output of this command should be the following:

   Failed to list services: rpc error: code = Unknown desc = OE0003: missing or invalid header 'mspid'
   

   This is expected because the orchestrator server expects some gRPC headers to be present but we did not provide them. Even if it is an error, since this response is from the server it is sufficient to tell your setup is working.