#NPM Connector

NPM Connector — это платформонезависимый коннектор, который можно использовать для подключения к любому NPM-реестру.

Вы можете использовать NPM Connector для безопасного выполнения операций NPM в CICD-пайплайнах или применять его в kubernetes-ворклоадах для выполнения операций NPM без необходимости наличия учетных данных.

Кроме того, вы можете централизованно управлять конфигурациями доступа к NPM по разным namespace, избегая необходимости повторять учетные данные NPM в каждом namespace.

#Overview

В этом документе рассматриваются:

• Integration Requirements: Предварительные требования к целевым NPM-реестрам
• Creating NPM connector
• Advanced Features: Возможности прокси и настройки NPM Connector

#Integration Requirements

Требования к NPM-реестрам

• NPM-реестр должен поддерживать NPM Registry API

#Creating a simple NPM connector

Как создать базовый NPM Connector:

# NPM Connector
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: npm-connector
spec:
  connectorClassName: npm
  address: https://registry.npmjs.org

#Fields Reference

spec.connectorClassName:

npm (константа), указывает имя ConnectorClass для интеграции с NPM.

spec.address:

Адрес целевого NPM-реестра, например: https://registry.npmjs.org.

При использовании Nexus в качестве npm-реестра необходимо указать адрес репозитория, например: https://nexus.example.com/repository/npm-public.

spec.auth (необязательно):

Указывает метод аутентификации для NPM-реестра

• spec.auth.name: должен быть basicAuth для NPM Connector.

• spec.auth.secretRef: указывает секрет, содержащий данные для аутентификации в NPM-реестре, секрет должен быть создан в том же namespace, что и коннектор. Если ваш NPM-реестр не требует аутентификации, это поле можно опустить.

Необязательные поля метаданных:

• cpaas.io/description: Описание для NPM Connector, например:

  apiVersion: connectors.alauda.io/v1alpha1
  kind: Connector
  metadata:
    name: npm-connector
    annotations:
      cpaas.io/description: "Connect to team development NPM registry"

spec.params (необязательно):

NPM Connector поддерживает параметры, которые используются для управления поведением конфигурации коннектора.

• spec.params[].name: Имя параметра, должно совпадать с именем параметра, определённым в соответствующем ConnectorClass.
• spec.params[].value: Значение параметра. Тип значения должен соответствовать типу параметра, определённому в ConnectorClass.

Поддерживаемые параметры:

• strict-ssl: указывает, будет ли в файлах .npmrc/.yarnrc.yml для NPM-реестра записан параметр strict-ssl. Значение по умолчанию — true. Поддерживаются значения true и false.

Пример:

spec:
  params:
    - name: strict-ssl
      value: "false"

#Capabilities of NPM Connector

#Authentication

NPM Connector поддерживает следующие типы аутентификации:

• basicAuth: аутентификация по имени пользователя и паролю, соответствующий тип секрета: kubernetes.io/basic-auth

Пример:

apiVersion: v1
stringData:
  username: your-npm-registry-username
  password: your-npm-registry-password
kind: Secret
metadata:
  name: npm-secret
type: kubernetes.io/basic-auth

Для получения полной информации о статусе см. Connector Status Documentation.

Если NPM-реестр не требует аутентификации, поле secretRef можно опустить:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: npm-connector
spec:
  connectorClassName: npm
  address: https://registry.npmjs.org
  auth:
    name: basicAuth

#Требуемые права для учетных данных

Необходимые права для настроенных учетных данных зависят от того, как вы планируете их использовать в Pods/Pipelines.

Например:

• Операции с пакетами: если вам нужно только скачивать зависимости с помощью npm install, учетные данные должны иметь права только на чтение целевого NPM-репозитория.
• Операции публикации и развертывания: если необходимо публиковать артефакты с помощью npm publish, учетные данные должны иметь права на чтение и запись для целевого репозитория.

Для обеспечения безопасности рекомендуется создавать учетные данные с минимально необходимыми правами. При необходимости дополнительных привилегий создавайте отдельные Connectors с более привилегированными секретами и используйте изоляцию namespace для контроля доступа пользователей к каждому Connector.

#Прокси и конфигурация NPM Connector с файлами npmrc и yarnrc.yml

Чтобы предоставить клиентам возможность доступа к NPM-реестру без учетных данных, NPM Connector предоставляет прокси-сервер, который автоматически внедряет информацию для аутентификации.

Клиенты могут использовать этот прокси-сервер для доступа к NPM-реестру без необходимости настраивать учетные данные на стороне клиента.

Для упрощения использования класс коннектора предоставляет файлы .npmrc и .yarnrc.yml, которые можно монтировать в Pods через CSI. В Pod при выполнении операций NPM прокси-сервис автоматически внедряет информацию для аутентификации.

#Адрес прокси

При создании Connector система автоматически разворачивает прокси-сервис для целевого NPM-реестра.

Адрес прокси записывается в status.proxy.httpAddress:

Пример:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: npm-connector
spec:
  # connector spec fields
status:
  conditions:
    # status conditions
  proxy:
    httpAddress:
      url: http://c-npm-connector.default.svc.cluster.local

#Конфигурационный файл .npmrc

NPM Connector предоставляет следующую конфигурацию:

.npmrc:

• Предоставляет конфигурационный файл .npmrc. В сочетании с connector-csi-driver этот файл монтируется в Pod, что позволяет обращаться к NPM-реестру через прокси без необходимости настраивать учетные данные на стороне клиента.

Пример конфигурационного файла, сгенерированного в Pod:

# NPM Registry Configuration
registry=http://npm-registry.example.com/

 # Токен аутентификации фиктивный, так как коннектор его не использует, он применяется для прокси-запросов.
//npm-registry.example.com/:_auth=fAd326jYkI123456789xxx

# Установка URL прокси коннектора для доступа к npm-реестру
https-proxy=http://connector-ns%2Fconnector-name:fAd326jYkI123456789xxx@c-npm-connector.default.svc.cluster.local/
proxy=http://connector-ns%2Fconnector-name:fAd326jYkI123456789xxx@c-npm-connector.default.svc.cluster.local/

# Отключение npm audit для избежания предупреждений безопасности в CI/CD
audit=false

# Отключение сообщений о финансировании для уменьшения шума вывода
fund=false

#Конфигурационный файл .yarnrc.yml

• Предоставляет конфигурационный файл .yarnrc.yml. В сочетании с connector-csi-driver этот файл монтируется в Pod, что позволяет обращаться к NPM-реестру через прокси без необходимости настраивать учетные данные на стороне клиента.

  # Установка URL сервера NPM-реестра для разрешения пакетов
  npmRegistryServer: "http://npm-registry.example.com/"
  
  # Токен аутентификации фиктивный, так как коннектор его не использует, он применяется для прокси-запросов.
  npmAuthIdent: "fAd326jYkI123456789xxx"
  
  # Всегда аутентифицироваться в реестре
  # Это необходимо для корректной работы коннектора, если npmAlwaysAuth не установлен в true, запросы метаданных не будут аутентифицированы.
  npmAlwaysAuth: true
  
  # unsafeHttpWhitelist используется для белого списка хостов для прокси-запросов.
  unsafeHttpWhitelist:
  - npm-registry.example.com
  
  # аутентификация для прокси-запросов
  httpProxy: "http://connector-ns%2Fconnector-name:fAd326jYkI123456789xxx@c-npm-connector.default.svc.cluster.local/"
  httpsProxy: "http://connector-ns%2Fconnector-name:fAd326jYkI123456789xxx@c-npm-connector.default.svc.cluster.local/"
  
  # Установка URL реестра для публикации пакетов
  # Обеспечивает публикацию пакетов в правильный реестр
  npmPublishRegistry: "http://npm-registry.example.com/"

Подробности о механике прокси см. в разделе How It Works в руководстве Quick Start.

export NODE_EXTRA_CA_CERTS=/opt/yarn/ca.cert # замените на фактический путь, где ca.cert смонтирован в Pod

#Файл ca.cert

NPM Connector также предоставляет файл ca.cert, содержащий CA-сертификат Connector Proxy. Этот файл можно смонтировать в Pod через Connector CSI Driver для установления доверия TLS при доступе к прокси по HTTPS.

#Использование Connectors CSI Driver для монтирования файлов .npmrc и .yarnrc.yml

NPM Connector предоставляет файлы .npmrc, .yarnrc.yml и ca.cert, которые можно монтировать в Pod через Connector CSI Driver.

Пример:

spec:

  volumes:
  - name: npmrc
    csi:
      readOnly: true
      driver: connectors-csi
      volumeAttributes:
        connector.name: "npm-connector"
        configuration.names: "npmrc"
  - name: yarnrc
    csi:
      readOnly: true
      driver: connectors-csi
      volumeAttributes:
        connector.name: "npm-connector"
        configuration.names: "yarnrc"

Описание параметров:

• csi.readOnly: фиксированное значение true
• csi.driver: драйвер Connector CSI, фиксированное значение connectors-csi.
• csi.volumeAttributes: атрибуты CSI Volume
  • connector.name: имя NPM Connector
  • connector.namespace: namespace NPM Connector; если не указано, используется namespace Pod
  • configuration.names: имя конфигурации, предоставляемое NPM Connector. Поддерживаются npmrc и yarnrc.

Подробную информацию о том, как использовать файлы .npmrc и .yarnrc.yml в Pod с помощью connectors-csi-driver, смотрите в разделе Using NPM Connectors in kubernetes jobs

#Further Reading

• Using NPM Connectors as Distribution Management Repository

#References

• Concepts of Connector
• Connector Proxy
• Connector CSI Driver
• Kubernetes CSI Volume