Lieutenant Integration

Vault can be used by Project Syn to store secrets for Syn-managed clusters. To do so, Lieutenant needs to be able to access Vault

Authenticate Lieutenant

Lieutenant needs to be able to authenticate itself to Vault. For that we add an authentication method for the Kubernetes cluster Lieutenant is running on.

We need to configure this authentication method slightly differently depending on whether Vault is running on the same Kubernetes cluster or not.

Vault on the same Kubernetes cluster

If Vault runs on the same Kubernetes cluster as Lieutenant, the authentication method configuration is already done.

External Vault

If Vault runs in a different Kubernetes cluster, we need to add a few extra configuration options.

config:
  auth_:
    lieutenant: (1)
      type: kubernetes
      config:
        kubernetes_host: https://api.example.com (2)
        disable_local_ca_jwt: true
        disable_iss_validation: true
        kubernetes_ca_cert: | (3)
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----

1	We recommend to change the authentication method mount path as the default `kubernetes` path should be reserved for the local cluster As documented in the parameters reference the key is used as field `path`.
2	This is the API URL of the Kubernetes cluster running Lieutenant
3	The CA of the Kubernetes API certificate. This is also necessary if the certificate is publicly trusted, due to a limitation of Vault.

Manage Access Policies

After enabling the authentication method for Lieutenant, we need to add roles and policies authorizing Lieutenant and the Syn-managed clusters to access Vault.

config:
  auth_:
    lieutenant: (1)
      roles: (2)
        syn-cluster: (4)
          bound_service_account_names: "*"
          bound_service_account_namespaces: lieutenant-prod
          policies: syn-cluster
          ttl: 1h
        lieutenant-operator: (5)
          bound_service_account_names: lieutenant-operator
          bound_service_account_namespaces: lieutenant-prod
          policies: lieutenant-operator
          ttl: 1h

  policies_: (3)
    syn-cluster: (4)
      rules: |
        path "clusters/kv/data/+/{{identity.entity.aliases.auth_kubernetes_5b636428.metadata.service_account_name}}/*" {
          capabilities = ["read"]
        }
    lieutenant-operator: (5)
      rules: |
        path "clusters/kv/data/*" {
          capabilities = ["read", "create", "update", "delete"]
        }
        path "clusters/kv/metadata/*" {
          capabilities = ["read", "create", "update", "delete", "list"]
        }
        path "clusters/kv/delete/*" {
          capabilities = ["update"]
        }

1	This snippet assumes that we’re configuring access for an external Vault instance. If you’re running Vault and Lieutenant on the same cluster, change this key to `kubernetes`.
2	When using the component’s `auth_` helper key, we can define roles as an object. This is transformed into a list with the keys as values for field `name` of each entry.
3	We define the policies using the component’s `policies_` helper key. The object keys are used as values for field `name` of each resulting list entry.
4	The `syn-cluster` policy allows each cluster to reveal its own secrets.
5	The `lieutenant-operator` policy allows the `lieutenant-operator` to read and write all secrets.

If service accounts or namespaces differ in your deployment, you will need to update the snippet above.

The policy syn-cluster allows ArgoCD to read the secrets of its cluster. The templating entry auth_kubernetes_5b636428 is a name generated by Vault after enabling the authentication method. Because the hash in this segment of the templating entry isn’t known in advance, the policy needs to be added in a second deployment after enabling the authentication method. The actual value of the segment needs to be fetched from the Vault instance after deploying the authentication method.

The entry is the Accessor name of the Kubernetes authentication method. If can either be fetched from the UI on the Access tab or from the CLI with:

vault auth list -detailed