#NPM Connector

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

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

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

#Обзор

Этот документ охватывает:

• Требования к интеграции: предварительные условия для целевых NPM registry
• Создание NPM connector
• Дополнительные возможности: возможности proxy и конфигурации NPM connector

#Требования к интеграции

Предварительные требования для NPM registry

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

#Создание простого 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

#Описание полей

spec.connectorClassName:

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

spec.address:

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

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

spec.auth(optional):

задает метод аутентификации NPM registry

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

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

Необязательные поля Metadata:

• 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(optional):

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

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

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

• registryType: задает роль этого connector, когда несколько NPM connector используются вместе в одном CSI volume. Этот параметр управляет тем, какой адрес registry используется для загрузки пакетов и какой — для публикации. Допустимые значения:

  • mirror — использовать registry этого connector для загрузки зависимостей (например, npm install)
  • publish — использовать registry этого connector для публикации пакетов (например, npm publish)
  • all — использовать registry этого connector и для загрузки, и для публикации
  • (пусто) — устаревшее поведение; когда ни у одного connector нет явного registryType, адрес текущего connector используется и для загрузки, и для публикации

  Когда хотя бы один connector имеет явный registryType, registry для загрузки определяется с приоритетом: mirror > all > publish > текущий connector. Registry для публикации определяется с приоритетом: publish > all > (пусто) > mirror > текущий connector.

  Этот параметр имеет смысл только при использовании нескольких connector в одном CSI volume. Для сценария с одним connector его можно не указывать.

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

Например:

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

#Возможности NPM Connector

#Аутентификация

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

• basicAuth: аутентификация на основе имени пользователя и пароля, соответствующий тип secret: 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.

Если NPM registry не требует аутентификации, можно опустить field 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 repository.
• Операции с пакетами и развертыванием: если вам нужно публиковать артефакты с помощью npm publish, учетные данные должны иметь права на чтение и запись для целевого repository.

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

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

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

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

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

#Адрес Proxy

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

Конечная точка proxy записывается в 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 registry через proxy без необходимости настраивать учетные данные на стороне клиента.

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

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

 # The authentication token is fake, because the connector will not use it, it will be used for proxy requests.
//npm-registry.example.com/:_auth=fAd326jYkI123456789xxx

# Set the connector proxy URL for npm registry access
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/

# Disable npm audit to avoid security warnings during CI/CD
audit=false

# Disable funding messages to reduce output noise
fund=false

#Файл конфигурации .yarnrc.yml

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

  # Set the NPM registry server URL for package resolution
  npmRegistryServer: "http://npm-registry.example.com/"
  
  # The authentication token is fake, because the connector will not use it, it will be used for proxy requests.
  npmAuthIdent: "fAd326jYkI123456789xxx"
  
  # Always authenticate to the registry
  # This is required for the connector to work correctly, if the npmAlwaysAuth is not set to true, the metadata request will not be authenticated.
  npmAlwaysAuth: true
  
  # The unsafeHttpWhitelist is used to whitelist the host for proxy requests.
  unsafeHttpWhitelist:
  - npm-registry.example.com
  
  # authentication for proxy requests
  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/"
  
  # Set the registry URL for package publishing
  # Ensures packages are published to the correct registry
  npmPublishRegistry: "http://npm-registry.example.com/"

Подробно о механизме работы proxy см. в разделе Как это работает руководства Quick Start.

export NODE_EXTRA_CA_CERTS=/opt/yarn/ca.cert # replace with the actual path where ca.cert is mounted in the Pod

#Файл ca.cert

NPM connector также предоставляет файл ca.cert, содержащий CA certificate Connector Proxy. Этот файл можно смонтировать в Pod через Connector CSI Driver, чтобы установить TLS trust при доступе к proxy по 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 Driver, фиксированное значение connectors-csi.
• csi.volumeAttributes: атрибуты CSI Volume
  • connector.name: имя NPM Connector
  • connector.namespace: namespace NPM Connector; если не указано, используется namespace Pod
  • configuration.names: имя configuration, предоставляемой NPM Connector. Как указано выше, поддерживаются npmrc и yarnrc.

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

#Дополнительные материалы

• Использование NPM Connectors как Distribution Management Repository

#Ссылки

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