Configuration

The native configuration format for Conch is a TOML file, passed as a command-line argument --config.

If you are installing Conch via Helm with a values.yaml then these settings can be set under the config key, e.g.:

config:
  issuer: "https://example.com"

All the examples below show the syntax for both.

issuer
Type:
String (URL)

This must be set as a string containing the URL of the OIDC issuer. It should be the path that contains the .well-known/openid-configuration location. For example, this could be set to "https://keycloak.example.com/realms/example" (such that https://keycloak.example.com/realms/example/.well-known/openid-configuration exists). The issuer must support OpenID Provider Issuer discovery.

client_id
Type:
String

The OIDC client ID that is configured at issuer. For example, it could be set to "clifton".

signing_key_path
Type:
String (path)

This must be set to the path on disk where the private SSH key is stored.

platforms
Type:
Table

The name of the table should be a string of the name of the platform. It must contain the following keys:

alias

a short string which can be used as an SSH config Host name. You should avoid making the alias a resolvable domain name as it works best if it forms its own namespace.

hostname

a string containing the real hostname of the platform to SSH into.

proxy_jump

a string containing the hostname to be used by ProxyJump.

For example, it might look like:

[platforms."batch.cluster1.example"]
alias = "cluster1.example"
hostname = "1.access.example.com"
proxy_jump = "bastion.example.com"

[platforms."batch.cluster2.example"]
alias = "cluster2.example"
hostname = "2.access.example.com"
proxy_jump = "bastion.example.com"
mappers
Type:
Array of Tables

This must be set to a list containing the identity mappers to apply. Each of these configure which claims (or combinations thereof) should be put into the certificate principals. The available options are:

single
Type:
String

A claim containing a single string should be placed verbatim into the principal list.

[[mappers]]
single = "email"
list
Type:
String

A claim containing a JSON list of strings, each of which will be mapped directly into the principal list.

[[mappers]]
list = "names"
project_infra
Type:
String

This will generate a principal for each of the projects passed in.

"v1"

Create principals of the form <short_name>.<project-name>. The prefix <short_name> comes from a string claim short_name and the <project-name> comes from each of the project names defined in the projects claim.

[[mappers]]
project_infra = "v1"

You can set as many mappers as you like, just repeat the table:

[[mappers]]
single = "email"

[[mappers]]
single = "short_name"

[[mappers]]
list = "names"
extensions
Type:
Array of Strings
Default:
[]

A list of the SSH certificate extensions that should be enabled on any generated certificates. For example:

extensions = ["permit-pty", "permit-agent-forwarding"]