# Установка nsctl с ручной подготовкой окружения

## Установка с ручной подготовкой окружения

```{warning}
Ручная подготовка нужна только в особых случаях, когда политики кластера не позволяют выполнить автоматизированную установку. 
Если у вас есть необходимые права, в том числе в коммунальном кластере, используйте [автоматизированную установку](./050_install_nsctl.md#автоматизированная-установка) с `deploymentType: both`; 
для коммунального кластера задайте `NamespacedGlobalConfiguration` и namespace в `config.yaml`. 
Подробные шаги приведены в [главе о коммунальном кластере](../043_kubernetes_advanced/010_shared_cluster.md#первая-установка-сразу-с-namespaced-конфигурацией).
```

Для коммунального кластера сначала ознакомьтесь с [отдельной главой](../043_kubernetes_advanced/010_shared_cluster.md).
Если для нужного namespace уже развернут `nsctl`, зарегистрирован CRD `NamespacedGlobalConfiguration` и настроены
необходимые права, для изменения конфигурации достаточно обновить `config.yaml` — повторно создавать CRD и роли не
нужно. Если чего-то из этого нет, согласуйте подготовку с администратором кластера.

Приведенный ниже пример `superuser-resources.yaml` предназначен для отдельного контура или для случая, когда
администратор явно согласовал такие права. В нем создается `ClusterRoleBinding` с широкими кластерными разрешениями; не
применяйте этот пример в коммунальном кластере без согласования.

Перед применением манифестов замените `<NAMESPACE>` на имя целевого пространства имен во всех YAML-фрагментах и командах
ниже.

Пример ниже сохраняет совместимость с текущим контроллером и дает кластерные права на конфигурации и события. Для
коммунального кластера согласуйте границы доступа
по [главе о коммунальном кластере](../043_kubernetes_advanced/010_shared_cluster.md#если-платформа-запрещает-автоматизированную-установку); этот пример не
обеспечивает изоляцию конфигураций разных команд.

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

      ```bash
      cat <<EOF | tee superuser-resources.yaml
      # Пространство имен
      apiVersion: v1
      kind: Namespace
      metadata:
        name: <NAMESPACE>
      ---
      # Роли
      apiVersion: rbac.authorization.k8s.io/v1
      kind: Role
      metadata:
        name: gs-ctk-role
        namespace: <NAMESPACE>
      rules:
        - apiGroups:
            - ""
            - apps
            - policy
            - rbac.authorization.k8s.io
            - coordination.k8s.io
            - networking.k8s.io
            - batch
          resources:
            - pods
            - configmaps
            - daemonsets
            - deployments
            - events
            - ingresses
            - jobs
            - persistentvolumeclaims
            - poddisruptionbudgets
            - replicasets
            - services
            - statefulsets
            - secrets
            - "pods/log"
            - "pods/exec"
            - "pods/attach"
            - leases
          verbs: [ "*" ]
      ---
      apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRole
      metadata:
        name: gs-ctk-cluster-role
      rules:
        - apiGroups:
          - global-system.ru
          - events.k8s.io
          resources:
          - "*"
          verbs:
          - "*"
      ---
      # Сервисный пользователь и его привязки к ролям
      apiVersion: v1
      kind: ServiceAccount
      metadata:
        name: gs-ctk-sa
        namespace: <NAMESPACE>
      ---
      apiVersion: rbac.authorization.k8s.io/v1
      kind: RoleBinding
      metadata:
        name: gs-ctk-role-bind
        namespace: <NAMESPACE>
      roleRef:
        apiGroup: rbac.authorization.k8s.io
        kind: Role
        name: gs-ctk-role
      subjects:
      - kind: ServiceAccount
        name: gs-ctk-sa
        namespace: <NAMESPACE>
      ---
      apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRoleBinding
      metadata:
        name: gs-ctk-cluster-role-bind
      roleRef:
        apiGroup: rbac.authorization.k8s.io
        kind: ClusterRole
        name: gs-ctk-cluster-role
      subjects:
      - kind: ServiceAccount
        name: gs-ctk-sa
        namespace: <NAMESPACE>
      EOF

      kubectl apply -f superuser-resources.yaml
      ```

   Команда `kubectl apply -f` создает описанные в файле ресурсы или обновляет их до состояния манифеста. В этом примере
   она применяется администратором к namespace, ролям, сервисной учетной записи и привязкам ролей.

2. При использовании Docker с авторизацией, необходимо
   подготовить [ресурс с секретом от репозитория](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#registry-secret-existing-credentials).

    ```bash
    docker login docker-registry.net # укажите здесь ваш репозиторий

    cat <<EOF | tee docker-secret.yaml
    apiVersion: v1
    kind: Secret
    metadata:
      name: docker-secret
      namespace: <NAMESPACE>
    data:
      .dockerconfigjson: $(cat ~/.docker/config.json | base64 | tr -d '\n')
    type: kubernetes.io/dockerconfigjson
    EOF

    kubectl apply -f docker-secret.yaml
    ```

3. Проверьте, зарегистрированы ли типы конфигурации Global ERP:

    ```sh
    kubectl api-resources --api-group=global-system.ru
    ```

   Если нужного типа конфигурации нет, попросите администратора применить соответствующий CRD из используемой поставки
   gs-ctk. Например, для установки обоих типов:

    ```sh
    kubectl apply -f ~/nscli/helm_chart/crds/crd.yaml
    kubectl apply -f ~/nscli/helm_chart/crds/namespaced_crd.yaml
    ```

   Если типы уже зарегистрированы, повторно применять CRD не требуется.

    ```{note}
    На этом этапе мы развернули все ресурсы, которые могут потребовать прав администратора. *Перед продолжением убедитесь, что вы переключились с контекста администратора на контекст непривилегированного пользователя.*
    ```

4. Подготовьте `values.yaml` по обычной инструкции развертывания. Обратите внимание, что при использовании Docker с
   авторизацией, требуется указать название секрета из 2 пункта в `imagePullSecret`.

   Системное NFS-хранилище используется также для автоматически выгружаемых дампов памяти. Его минимальный объём —
   **5–6 размеров максимального `-Xmx`, но не менее 120 ГБ**; см.
   [расчёт объёма](../043_kubernetes_advanced/020_min_requirements.md#системное-nfs-хранилище-кластера).

    ```yaml
    # Реестр образов
    imageRepository: "docker-registry.net"
    # Тег образов, по-умолчанию равен версии чарта
    imageTag: ""
    # Секрет загрузки с репозитория
    imagePullSecret: "" # "docker-secret" - ваш секрет с учетной записью докер-реестра

    # Тип развертывания:
    #  "cluster" - будут сгенерированы только ресурсы уровня кластера (пространство имен, роли)
    #  "namespace" - будут сгенерированы только ресурсы уровня пространства имен (ConfigMap, ресурс с контроллером)
    #  "both" - все ресурсы, значение по умолчанию. Обычно не требует изменения.
    deploymentType: namespace

    # Часовой пояс
    timezone: "Europe/Moscow"

    # Режим отладки для nsctl
    nsctlDebugEnabled: false

    # Суффикс, добавляемый к названию релиза, чтобы получить название пространства имен
    namespaceSuffix: ""

    # Системное NFS-хранилище для комплектов групп, приложений и дампов памяти
    # Минимальный объём: 5–6 размеров максимального Xmx, но не менее 120 ГБ
    systemVolume:
        nfs:
            server: "nfs.server"
            path: /export

    # Субъекты RoleBinding/ClusterRoleBinding, которым стоит предоставить права по
    # управлению GlobalConfiguration, ресурсами в пространстве имен. Можно
    # использовать для предоставления прав администраторам GlobalERP. Например:
    #privilegedSubjects:
    #- kind: User
    #  name: gs_admin
    privilegedSubjects: []

    # Переопределение ServiceAccount для установки nsctl и другим подам.
    # По умолчанию используются пользователи, созданные этим Helm-чартом на уровне
    # кластера.
    overrideNsctlServiceAccount: gs-ctk-sa
    overrideWorkerServiceAccount: gs-ctk-sa

    # Аннотации подов
    podAnnotations: {}
    # Лейблы подов
    podLabels: {}
    # Селекторы нод для подов
    nodeSelector: {}
    # Tolerations для подов
    tolerations: []
    # Affinity для подов
    affinity: {}
    ```

    ```{note}
       Весь список параметров смотрите в `values.yaml` из чарта. Получить `values.yaml` из скачанного отдельно Helm-чарта можно при помощи команды `helm show values gs-ctk-helm-chart-SNAPSHOT.tgz > values.yaml`.

       Документация по параметрам Helm-чарта доступна [здесь](../043_kubernetes_advanced/030_chart.md).
    ```

   Обратите внимание, что должны быть установлены следующие параметры:

    ```yaml
    deploymentType: namespace # указывает, что разворачивать пространство имен и роли не требуется
    overrideNsctlServiceAccount: gs-ctk-sa # созданный ранее ServiceAccount
    overrideWorkerServiceAccount: gs-ctk-sa # созданный ранее ServiceAccount
    ```

    ```{note}
    Если для работы gs-ctk требуются [Tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) или [`nodeSelector`](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector), укажите их здесь, в values.yaml
    ```

5. Разверните ресурсы уровня пространства имен (ресурс контроллера `nsctl` и `ConfigMap` с параметрами) с правами
   непривилегированного пользователя:

    ```sh
    helm upgrade \
         --install \
         gs-ctk \
         ~/nscli/helm_chart \
         -f values.yaml \
         --namespace "<NAMESPACE>" \
         --skip-crds
    ```

    ```{note}

    Если не указать `--skip-crds`, то высока вероятность, что у вашего пользователя не хватит прав на развертывание.

    ```

    ```text
    NAME: gs-ctk
    LAST DEPLOYED: Tue Jan 19 03:14:08 2038
    NAMESPACE: <NAMESPACE>
    STATUS: deployed
    REVISION: 1
    TEST SUITE: None
    NOTES:
    =====================================

    GS-CTK
    Версия SNAPSHOT-6.2.5
    Copyright © 2000-2026
    Компания «Бизнес Технологии»
    Все права защищены.

    =====================================
    Развернут в пространстве имен `<NAMESPACE>`.
    (venv)
    ```

6. Проверьте, что под `nsctl` находится в состоянии `Running`.

   На развертывание может потребоваться некоторое время, так как требуется скачать образ контейнера и запустить его.
   Обычно это занимает не больше пяти минут.

    ```bash
    kubectl get pods --namespace "<NAMESPACE>"
    ```

    ```text
    NAME                     READY   STATUS    RESTARTS   AGE
    nsctl-84cb5578fd-b2c5x   1/1     Running   0          1h
    ```

Если `nsctl` запуcтился, у вас должно быть все готово к переходу [к созданию секретов](./070_create_secrets.md).
