Установка#

В руководстве приведены инструкции по установке компонента «Управление ключами и сертификатами».

Состав дистрибутива#

В состав дистрибутива KACM входит:

Элемент дистрибутива

Описание

./documentation

Документация

./package/conf/helm

Helm charts для установки и настройки компонента «Управление ключами и сертификатами»

./package/bin

Директория, содержащая в себе Dockerfile и бинарные файлы, необходимые для сборки образов компонента «Управление ключами и сертификатами»

Состав дистрибутива может быть расширен дополнительными конфигурациями, учитывающими прикладные требования клиента. Конфигурация может представлять собой Helm Chart, применяемый следующей командой: helm install kacm-cert-manager .

Выбор способа установки#

Установка компонента «Управление ключами и сертификатами» выполняется с помощью Helm Chart.

Подготовка окружения#

Перед установкой проверьте соблюдение следующих условий:

  1. Развернут и настроен кластер Kubernetes версии 1.19 или выше, в соответствии с требованиями, предъявляемыми к Платформе.

  2. Для доступа в Kubernetes c использованием консоли на рабочем месте должен быть установлен клиент Kubernetes (kubectl), совместимой с кластером Kubernetes.

  3. Должен быть установлен helm, версии не ниже 3.10.

  4. На один кластер может быть одновременно установлен только один экземпляр компонента «Управление ключами и сертификатами».

Каких-либо требований безопасности к рабочему окружению и к платформе Kubernetes со стороны компонента «Управление ключами и сертификатами» не предъявляется.

Базовый образ#

Для сборки образов компонент необходимо предварительно подготовить базовый образ, на основе которого должны собираться образы компонента «Управление ключами и сертификатами».

К базовому образу предъявляется следующее требование:

  • в базовом образе необходимо наличие пользователя с ID 1337 (UID), принадлежащего группе с ID 1337 (GID), при условии, что значения UID и GID, задаваемые в Dockerfile компонента, не будут переопределяться платформой Kubernetes (директивы runAsUser и runAsGroup) во время исполнения.

Возможна сборка базового образа KACM на основе sberlinux.

Если необходимо закрыть возможность запуска исполняемой оболочки (shell или bash), можно удалить исполняемые файлы оболочек в Dockerfile для сборки базового образа:

FROM repo/sberlinux:latest
 
RUN rm /bin/bash
RUN rm /bin/sh

Если базовый образ был предоставлен в виде архива, то загрузить его в ваш реестр образов можно следующими командами:

  1. Загрузка образа из архива в локальный реестр образов:

docker load < <архив_с_образом>

  1. Если требуется изменить tag загруженного из архива образа:

docker tag <старый_tag> <новый_tag>

  1. Загрузка образа в реестр образов:

docker push <tag>

Для сборки образа необходимо:

  1. Проверить название образа перед push, чтобы был прописан полный путь.

  2. Для каждого компонента перейти в папку package/bin/<название_компонента>.

  3. Для сборки образа в качестве аргумента передать базовый образ:

docker build --build-arg BASE_IMAGE=<базовый_образ> -t <tag_компонента> .

Установка с помощью Helm#

Для установки Helm charts выполните следующую команду:

helm install <имя_шаблона> <путь_к_папке_с_Helm_charts> --namespace <имя_проекта_для_установки>

Пример:

helm install istio-base istio/base -n istio-system

Аргументы можно задать в файле values.yaml в той же папке или же через аргумент --set.

helm install <имя_шаблона> <путь_к_папке_с_Helm_charts> --namespace <имя_проекта_для_установки> --set <путь_к_ключ>=<значение>

Пример:

helm install <имя_шаблона> <путь_к_папке_с_Helm_charts> --namespace <имя_проекта_для_установки> --set watchedNamespaces=istio-system --set operator.resources.cpu=200m

Ниже приведен пример values для развертывания Helm Chart компонента «Управление ключами и сертификатами»:

certManager:
  controller:
    image: docker.io/kacm-cert-manager/controller:1.0
    replicas: 1
    resources:
      limits: { "cpu": "200m", "memory": "200Mi" }
      requests: { "cpu": "100m", "memory": "100Mi" }

  cainjector:
    image:  docker.io/kacm-cert-manager/cainjector:1.0
    replicas: 1
    resources:
      limits: { "cpu": "300m", "memory": "300Mi" }
      requests: { "cpu": "200m", "memory": "200Mi" }

  startupApiCheck:
    image: docker.io/kacm-cert-manager/startupapicheck:4.8.0-ALPHAv1
    backoffLimit: 4
    resources:
      limits: { "cpu": "200m", "memory": "200Mi" }
      requests: { "cpu": "100m", "memory": "100Mi" }

  imagePullSecrets:
    - image-pull

clusterIssuer:
  type: secret 
  secretName: myTLSSecret #Обязательно, если type: secret, имя секрета с ключевой парой

Структура Helm Chart#

Структура values Helm Chart компонента «Управление ключами и сертификатами»:

Структура Values

Название

Опциональность

Тип

Описание

certManager

Опционально

certManager

Описывает развертывание элементов компонента KACM. Если поле отсутствует, то не ставит программные компоненты KACM и необходимые для их функционирования ресурсы k8s

clusterIssuer

Опционально

clusterIssuer

Описывает развертывание ClusterIssuer, для создания централизованного CA в рамках кластера k8s

configMap

Опционально

configMap

Описывает развертывание ConfigMap, для ограничения области ответственности KACM

Структура Values.certManager

Название

Опциональность

Тип

Описание

isOpenShift

Опционально

bool

Описывает развертывание компонентов KACM в OpenShift

controller

Опционально

controller

Описывает развертывание программного компонента controller. Если поле отсутствует, то данный программный компонент не ставится

cainjector

Опционально

cainjector

Описывает развертывание программного компонента cainjector. Если поле отсутствует, то данный программный компонент не ставится

startupApiCheck

Опционально

startupApiCheck

Описывает развертывание программного компонента startupApiCheck. Если поле отсутствует, то данный программный компонент не ставится

installRBAC

Опционально

bool

Описывает развертывание ролевой модели KACM. Если поле отсутствует, то ролевая модель будет развернута

installAggregateRoles

Опционально

bool

Описывает развертывание ролевой к ресурсам security.synapse.sber для пользователей. Если поле отсутствует, то ролевая модель будет развернута

enableMultitenancy

Опционально

bool

Описывает включение режима (multitenancy) ограничения области ответственности KACM

imagePullSecrets

Опционально

array

Описывает список секретов, необходимых для скачивания образов платформой оркестрации

Структура Values.certManager.controller

Название

Опциональность

Тип

Описание

image

Обязательно

string

Docker образ с программным компонентом controller

imagePullPolicy

Опционально

string

Описывает развертывание ClusterIssuer, для создания централизованного CA в рамках кластера k8s

replicas

Обязательно

int

Количество реплик программного компонента

resources

Обязательно

struct

Описание лимитов и запросов на ресурсы кластера k8s

Структура Values.certManager.cainjector

Название

Опциональность

Тип

Описание

image

Обязательно

string

Docker образ с программным компонентом cainjector

imagePullPolicy

Опционально

string

Политика загрузки образа при старте Pod. При отсутствии поля будет Always

replicas

Обязательно

int

Количество реплик программного компонента

resources

Обязательно

struct

Описание лимитов и запросов на ресурсы кластера k8s

Структура Values.certManager.startupApiСheck

Название

Опциональность

Тип

Описание

image

Обязательно

string

Docker образ с программным компонентом startupApiСheck

imagePullPolicy

Опционально

string

Политика загрузки образа при старте Pod. При отсутствии поля будет Always

backoffLimit

Обязательно

int

Количество перезапусков Job в случае неудачи

resources

Обязательно

struct

Описание лимитов и запросов на ресурсы кластера k8s

Структура Values.clusterIssuer

Название

Опциональность

Тип

Описание

name

Обязательно

string

Переопределение имени ClusterIssuer, по умолчанию kacm-issuer

commonName

Обязательно

string

Common Name, использующийся в сертификатах

configMapLabels

Опционально

bool

Нужно ли вписывать LS Configmap-ы в labels ClusterIssuer (используется при multitancy mode)

type

Опционально

string

Тип CluserIssuer. Возможные значения:
1.selfsigned - Issuer на базе сгенерированного самоподписанного сертификата
2.secret - Создание Issuer на основе существующей ключевой пары в секрете k8s

selfsigndedOptions

Опционально

selfsigndedOptions

Настройки cамоподписанного Issuer

secretName

Обязательно если type: secret

string

Имя секрета k8s, с ключевой парой которого будут подписываться сертификаты

Структура Values.certManager.startupApiСheck.selfsigndedOptions / Values.clusterIssuer.selfsigndedOptions

Название

Опциональность

Тип

Описание

duration

Опционально

string

Переопределение параметра времени жизни сертификата, по умолчанию 8456h

renewBefore

Опционально

string

Переопределение параметра времени, после которого будет происходить ротация сертификата, по умолчанию 2400

Структура Values.configMap

Название

Опциональность

Тип

Описание

labelSelectors

Опционально

struct

Список labels, который должен иметь ресурс, чтобы быть в области видимости KACM при режиме multitenancy

Ресурсы для работы компонента#

RBAC#

Тип ресурса

Название

Влияет на компонент

Назначение

ClusterRole

kacm-cert-manager-cainjector

cainjector

Роль для работы компонента cainjector с KubeAPI

ClusterRoleBinding

kacm-cert-manager-cainjector

cainjector

Привязка роли kacm-cert-manager-cainjector для сервис аккаунта kacm-cert-manager-cainjector

Role

kacm-cert-manager-cainjector:leaderelection

cainjector

Роль для работы механизма leaderElection

RoleBinding

kacm-cert-manager-cainjector:leaderelection

cainjector

Привязка роли для работы механизма leaderElection

ClusterRole

kacm-cert-manager-controller-issuers

controller

Роль для обработки кастомного ресурса Issuer

ClusterRole

kacm-cert-manager-controller-clusterissuers

controller

Роль для обработки кастомного ресурса ClusterIssuer

ClusterRole

kacm-cert-manager-controller-certificates

controller

Роль для обработки кастомного ресурса Certificate и CertificateRequest

ClusterRoleBinding

kacm-cert-manager-controller-issuers

controller

Привязка роли kacm-cert-manager-controller-issuers

ClusterRoleBinding

kacm-cert-manager-controller-clusterissuers

controller

Привязка роли kacm-cert-manager-controller-clusterissuers

ClusterRoleBinding

kacm-cert-manager-controller-certificates

controller

Привязка роли kacm-cert-manager-controller-certificates

Role

kacm-cert-manager-startupapicheck:create-cert

cainjector

Роль для работы механизма leaderElection

RoleBinding

kacm-cert-manager-startupapicheck:create-cert

cainjector

Привязка роли для работы механизма leaderElection

ClusterRole:kacm-cert-manager-cainjector

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: kacm-cert-manager-cainjector
rules:
  - apiGroups: ["security.synapse.sber"]
    resources: ["certificates"]
    verbs: ["get", "list", "watch"]
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: ["get", "list", "watch"]
  - apiGroups: [""]
    resources: ["events"]
    verbs: ["get", "create", "update", "patch"]
  - apiGroups: ["admissionregistration.k8s.io"]
    resources: ["validatingwebhookconfigurations", "mutatingwebhookconfigurations"]
    verbs: ["get", "list", "watch", "update", "patch"]
  - apiGroups: ["apiregistration.k8s.io"]
    resources: ["apiservices"]
    verbs: ["get", "list", "watch", "update", "patch"]
  - apiGroups: [ "apiextensions.k8s.io" ]
    resources: [ "customresourcedefinitions" ]
    resourceNames: ["certificates.security.synapse.sber"]
    verbs: [ "get" ]
  - apiGroups: [""]
    resources: ["configmaps"]
    verbs: ["get", "list", "watch"]
  - apiGroups: [""]
    resources: ["namespaces"]
    verbs: ["get", "list", "watch"]

ClusterRoleBinding:kacm-cert-manager-cainjector

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: kacm-cert-manager-cainjector
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: kacm-cert-manager-cainjector
subjects:
  - name: kacm-cert-manager-cainjector
    namespace: $MyNamespace
    kind: ServiceAccount

Role:kacm-cert-manager-cainjector:leaderelection

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: kacm-cert-manager-cainjector:leaderelection
  namespace: {{.Release.Namespace}}
  labels:
    app: cainjector
    app.kubernetes.io/name: cainjector
    app.kubernetes.io/instance: kacm-cert-manager
    app.kubernetes.io/component: "cainjector"
    app.kubernetes.io/managed-by: Helm
    platformv.sber.ru/productCode: "SSM"
    platformv.sber.ru/componentCode: "KACM"
rules:
  - apiGroups: ["coordination.k8s.io"]
    resources: ["leases"]
    resourceNames: ["cert-manager-cainjector-leader-election", "cert-manager-cainjector-leader-election-core"]
    verbs: ["get", "update", "patch"]
  - apiGroups: ["coordination.k8s.io"]
    resources: ["leases"]
    verbs: ["create"]

RoleBinding:kacm-cert-manager-cainjector:leaderelection

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: kacm-cert-manager-cainjector:leaderelection
  namespace: {{.Release.Namespace}}
  labels:
    app: cainjector
    app.kubernetes.io/name: cainjector
    app.kubernetes.io/instance: kacm-cert-manager
    app.kubernetes.io/component: "cainjector"
    app.kubernetes.io/managed-by: Helm
    platformv.sber.ru/productCode: "SSM"
    platformv.sber.ru/componentCode: "KACM"
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: kacm-cert-manager-cainjector:leaderelection
subjects:
  - kind: ServiceAccount
    name: kacm-cert-manager-cainjector
    namespace: {{.Release.Namespace}}

ClusterRole:kacm-cert-manager-controller-issuers

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: kacm-cert-manager-controller-issuers
rules:
  - apiGroups: ["security.synapse.sber"]
    resources: ["issuers", "issuers/status"]
    verbs: ["update", "patch"]
  - apiGroups: ["security.synapse.sber"]
    resources: ["issuers"]
    verbs: ["get", "list", "watch"]
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: ["get", "list", "watch", "create", "update", "delete"]
  - apiGroups: [""]
    resources: ["events"]
    verbs: ["create", "patch"]
  - apiGroups: [ "" ]
    resources: [ "configmaps" ]
    verbs: [ "get", "list", "watch", "create", "update", "delete" ]

ClusterRole:kacm-cert-manager-controller-clusterissuers

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: kacm-cert-manager-controller-clusterissuers
rules:
  - apiGroups: ["security.synapse.sber"]
    resources: ["clusterissuers", "clusterissuers/status"]
    verbs: ["update", "patch"]
  - apiGroups: ["security.synapse.sber"]
    resources: ["clusterissuers"]
    verbs: ["get", "list", "watch"]
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: ["get", "list", "watch", "create", "update", "delete"]
  - apiGroups: [""]
    resources: ["events"]
    verbs: ["create", "patch"]
  - apiGroups: [ "" ]
    resources: [ "configmaps" ]
    verbs: [ "get", "list", "watch", "create", "update", "delete" ]

ClusterRole:kacm-cert-manager-controller-certificates

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: kacm-cert-manager-controller-certificates
rules:
  - apiGroups: ["security.synapse.sber"]
    resources: ["certificates", "certificates/status", "certificaterequests", "certificaterequests/status"]
    verbs: ["update", "patch"]
  - apiGroups: ["security.synapse.sber"]
    resources: ["certificates", "certificaterequests", "clusterissuers", "issuers"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["security.synapse.sber"]
    resources: ["certificates/finalizers", "certificaterequests/finalizers"]
    verbs: ["update"]
  - apiGroups: [ "security.synapse.sber" ]
    resources: [ "certificates", "certificaterequests" ]
    verbs: [ "create", "update", "delete" ]
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: ["get", "list", "watch", "create", "update", "delete", "patch"]
  - apiGroups: [""]
    resources: ["events"]
    verbs: ["create", "patch"]
  - apiGroups: [ "" ]
    resources: [ "namespaces" ]
    verbs: [ "get", "list" ]
  - apiGroups: [ "" ]
    resources: [ "configmaps" ]
    verbs: [ "get", "list", "watch", "create", "update", "delete" ]

ClusterRoleBinding:kacm-cert-manager-controller-issuers

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: kacm-cert-manager-controller-issuers
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: kacm-cert-manager-controller-issuers
subjects:
  - name: kacm-cert-manager
    namespace: {{.Release.Namespace}}
    kind: ServiceAccount

ClusterRoleBinding:kacm-cert-manager-controller-clusterissuers

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: kacm-cert-manager-controller-clusterissuers
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: kacm-cert-manager-controller-clusterissuers
subjects:
  - name: kacm-cert-manager
    namespace: {{.Release.Namespace}}
    kind: ServiceAccount

ClusterRoleBinding:kacm-cert-manager-controller-certificates

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: kacm-cert-manager-controller-certificates
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: kacm-cert-manager-controller-certificates
subjects:
  - name: kacm-cert-manager
    namespace: {{.Release.Namespace}}
    kind: ServiceAccount

Role:kacm-cert-manager-startupapicheck:create-cert

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: kacm-cert-manager-startupapicheck:create-cert
  namespace: {{.Release.Namespace}}
  annotations:
    helm.sh/hook: post-install
    helm.sh/hook-delete-policy: before-hook-creation,hook-succeeded
    helm.sh/hook-weight: "-5"
rules:
  - apiGroups: ["security.synapse.sber"]
    resources: ["certificates"]
    verbs: ["create"]

RoleBinding:kacm-cert-manager-startupapicheck:create-cert

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: kacm-cert-manager-startupapicheck:create-cert
  namespace: {{.Release.Namespace}}
  annotations:
    helm.sh/hook: post-install
    helm.sh/hook-delete-policy: before-hook-creation,hook-succeeded
    helm.sh/hook-weight: "-5"
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: kacm-cert-manager-startupapicheck:create-cert
subjects:
  - kind: ServiceAccount
    name: kacm-cert-manager-startupapicheck
    namespace: {{.Release.Namespace}}

Пользовательские роли#

В данном разделе перечисленны ресурсы для предоставления прав на API security.synapse.sber для стандартных пользовательских ролей k8s

Тип ресурса

Название

Влияет на компонент

Назначение

ClusterRole

kacm-cert-manager-cluster-view

-

Просмотр Cluster пользовательских ресурсов security.synapse.sber

ClusterRole

kacm-cert-manager-view

-

Просмотр Namespaced пользовательских ресурсов security.synapse.sber

ClusterRole

kacm-cert-manager-edit

-

Роль для редактирования пользовательских ресурсов security.synapse.sber

kacm-cert-manager-cluster-view

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: kacm-cert-manager-cluster-view
  labels:
    rbac.authorization.k8s.io/aggregate-to-cluster-reader: "true"
rules:
  - apiGroups: ["security.synapse.sber"]
    resources: ["clusterissuers"]
    verbs: ["get", "list", "watch"]

kacm-cert-manager-view

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: kacm-cert-manager-view
  labels:
    rbac.authorization.k8s.io/aggregate-to-view: "true"
    rbac.authorization.k8s.io/aggregate-to-edit: "true"
    rbac.authorization.k8s.io/aggregate-to-admin: "true"
    rbac.authorization.k8s.io/aggregate-to-cluster-reader: "true"
rules:
  - apiGroups: ["security.synapse.sber"]
    resources: ["certificates", "certificaterequests", "issuers"]
    verbs: ["get", "list", "watch"]

kacm-cert-manager-edit

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: kacm-cert-manager-edit
  labels:
    rbac.authorization.k8s.io/aggregate-to-edit: "true"
    rbac.authorization.k8s.io/aggregate-to-admin: "true"
rules:
  - apiGroups: ["security.synapse.sber"]
    resources: ["certificates", "certificaterequests", "issuers"]
    verbs: ["create", "delete", "deletecollection", "patch", "update"]
  - apiGroups: ["security.synapse.sber"]
    resources: ["certificates/status"]
    verbs: ["update"]