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 thathttps://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"
platforms: batch.cluster1.example: alias: "cluster1.example" hostname: "1.access.example.com" proxy_jump: "bastion.example.com" 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"
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"
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 claimshort_name
and the<project-name>
comes from each of the project names defined in theprojects
claim.
[[mappers]] project_infra = "v1"
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"
mappers: - single: "email" - single: "short_name" - 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"]