Installation¶
Conch can be deployed in a few different way, but all require a private SSH signing key to be created:
$ ssh-keygen -q -t ed25519 -f ssh_signing_key -C '' -N ''
Conch reads the signing key live on each signing request. This means that if you replace the private key on disk, any future requests will use it.
Helm¶
First, create the SSH signing key and put it in a Secret
:
$ kubectl create secret generic conch-signing-key-secret --from-file=key=ssh_signing_key
$ rm ssh_signing_key
then, you can create a values.yaml
(see Configuration for details) like:
---
config:
issuer: "..."
platforms: [...]
mappers: [...]
extensions: [...]
Note that the Helm chart manages the config value signing_key_path
for you by mounting the file as a read-only volume so you do not need to set it.
You can then install the chart with:
$ helm upgrade conch oci://ghcr.io/isambard-sc/charts/conch --version x.y.z --install --values values.yaml
OCI image¶
Conch can be deployed as a container using e.g. Podman.
Set up a config file conch.toml
as described in Configuration and run the container, mounting both the config file and the signing key itself:
$ podman run \
-v conch.toml:/conch.toml \
-v ssh_signing_key:/signing_key \
-e RUST_LOG=info \
ghcr.io/isambard-sc/conch:0.1.4 --config=/conch.toml
Binary¶
Conch can be run as a simple binary. They can be downloaded from releases.
Create the config file as described in Configuration (editing it to point to the local location of the signing key). You can then run it with:
$ env RUST_LOG=info conch --config=conch.toml
OIDC¶
All the methods above require an OIDC issuer to be specified. Any client communicating with Conch (e.g. Clifton) will need to provide an access token (in JWT format) which Conch will validate against the issuer. This means that the issuer that the client uses must match the issuer configured in Conch.
Claims required¶
When requesting an SSH certificate from Conch, a user must authenticate themselves by passing a JSON Web Token.
Conch will validate this JWT by checking that is was signed by an issuer
that you define.
There are three JWT claims that Conch requires in order to generate the response containing the signed certificate:
email
This must be a string containing some unique identifier for the user. Usually this is the email address of the user.
short_name
This must be a string containing a UNIX username-compatible name.
If using the
project_infra
version 1 mapper, this will be combined with the project names to create the principals in the certificate.projects
This must be a JSON object containing a string key for each project name, with the value being a list of objects containing a
name
member giving the project name and aresources
member giving the platforms (seeplatforms
) that the project is available on. For example, this could look like:{ "project-a": { "name": "Project A", "resources": [ { "name": "batch.cluster1.example", "username": "user.proj-a" }, { "name": "batch.cluster2.example", "username": "user.proj-a" } ] }, "project-b": { "name": "Project B", "resources": [ { "name": "batch.cluster2.example", "username": "user.proj-b" } ] } }