How to deploy the Orchestrator¶
This guide shows you how to deploy the Orchestrator component of Substra.
Prerequisites¶
To deploy the Orchestrator you will need a fully configured Kubernetes cluster. You will also need some tools:
Preparing your Helm values¶
The orchestrator deployment is packaged using Helm. You can find the complete description of values that can be used to configure the chart on Artifact Hub.
Add the Helm repository for Substra:
helm repo add substra https://substra.github.io/charts/
Create a Helm values file named
orchestrator-values.yaml
with the following content:ingress: enabled: true hostname: HOSTNAME
ReplaceHOSTNAME
with the hostname of your Orchestrator.This will setup the ingress to make your Orchestrator accessible at the defined hostname.
Setup your Substra channels. In the
orchestrator-values.yaml
file, add the following content:channels: - name: CHANNEL-NAME organizations: [ORG-NAME, ...]
ReplaceCHANNEL-NAME
with the name you want to give to your channel.ReplaceORG-NAME, ...
with the names of the Organizations that you want to include in this channel.If you want more than one channel you can add more items in the list.
Here you have created the configuration required to have a running orchestrator that can support a Substra network. If you want you can jump directly to the section Deploy the Chart. You can also follow along the next sections to enhance the security of your orchestrator.
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:
Enable TLS, in the
orchestrator-values.yaml
file add the following content:orchestrator: tls: enabled: true
Generate a self-signed Certificate Authority:
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
Generate a private key for signing certificates:
openssl genrsa -out orchestrator-ca.key 2048
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
Generate a certificate for the Orchestrator
Generate a certificate signing request:
openssl req -newkey rsa:2048 -nodes -keyout orchestrator-tls.key -subj "/CN=HOSTNAME" -out orchestrator-cert.csr
ReplaceHOSTNAME
with the hostname of your Orchestrator. This should be the sameHOSTNAME
as in the ingress configuration.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
andorchestrator-cert.csr
.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:HOSTNAME")
ReplaceHOSTNAME
with the hostname of your Orchestrator.Caution
We don’t recommend having your certificate valid for a year, you should change this value based on your company policy.
Delete the Certificate Signing Request:
rm orchestrator-cert.csr orchestrator-ca.srl
Create a Kubernetes ConfigMap for the CA certificate:
kubectl create configmap orchestrator-tls-cacert --from-file=ca.crt=orchestrator-ca.crt
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
Optional: If you also want to setup mTLS to authenticate your client follow the guide How to set up mTLS.
Deploy the Chart¶
To deploy the orchestrator in your Kubernetes cluster follow these steps:
Deploy the Orchestrator Helm chart:
helm install RELEASE-NAME substra/orchestrator --version VERSION --values orchestrator-values.yaml
ReplaceRELEASE-NAME
with the name of your orchestrator release (it can be any arbitrary name).ReplaceVERSION
with the version of the orchestrator helm chart you want to deploy.This will create all the Kubernetes resources required for a functional Orchestrator in your Kubernetes cluster.
Validate that the deployment was successful:
grpcurl [--cacert orchestrator-ca.crt] HOSTNAME:443 list
ReplaceHOSTNAME
with the hostname of your orchestrator.Add the--cacert
argument if you deployed your orchestrator with TLS.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.