Este documento foi traduzido usando tecnologia de tradução automática de máquina. Sempre trabalhamos para apresentar traduções precisas, mas não oferecemos nenhuma garantia em relação à integridade, precisão ou confiabilidade do conteúdo traduzido. Em caso de qualquer discrepância, a versão original em inglês prevalecerá e constituirá o texto official.

Ambiente air-gapped

SUSE® Rancher Prime Cluster API oferece suporte para um ambiente air-gapped de forma nativa, aproveitando os recursos do Cluster API Operator, a dependência necessária para instalar SUSE® Rancher Prime Cluster API.

Para provisionar e configurar provedores do Cluster API, o Turtles utiliza o recurso CAPIProvider para permitir o gerenciamento dos manifests do Cluster API Operator de forma declarativa. Cada campo fornecido pelo recurso upstream do CAPI Operator para o spec.type desejado também está disponível no spec do recurso CAPIProvider.

Uma nova instalação do SUSE® Rancher Prime Cluster API inclui apenas o provedor CAPI kernel e seus CRDs. O mecanismo de instalação padrão para este provedor não requer a obtenção do manifest de uma fonte remota, portanto, é totalmente funcional em um ambiente air-gapped, pois recupera a definição YAML de um ConfigMap local, embutido no gráfico da aplicação.

A versão do CAPI kernel enviada com o SUSE® Rancher Prime Cluster API é testada e validada ativamente, e o gráfico é pré-configurado para selecionar esta versão por padrão usando o CAPI Operator. No entanto, se você tiver requisitos específicos sobre versionamento ou qual repositório usar, ainda pode personalizar o comportamento do CAPI Operator com seu próprio fetchConfig.

Usuários Prime

Usuários Prime: Usuários do Rancher Prime se beneficiam dos artefatos OCI do provedor CAPI pré-espelhados disponíveis no Rancher Prime Registry (registry.rancher.com). Esses provedores são automaticamente validados, testados e mantidos para sua versão do Turtles. Para ver quais provedores e versões estão disponíveis para sua versão do Turtles, consulte o arquivo de configuração config-prime.yaml.

Esta seção fornece orientações sobre como usar CAPIProvider e a funcionalidade do CAPI Operator em diferentes cenários air-gapped.

Prefixação automática de registro com o Rancher Default Registry

Pré-requisitos

Certifique-se de que o registro privado configurado na configuração system-default-registry do Rancher contenha imagens espelhadas para todos os provedores CAPI que você pretende usar. Os caminhos das imagens dentro do registro espelhado devem preservar a estrutura original do namespace e do nome da imagem (por exemplo, cluster-api/cluster-api-controller). Consulte os arquivos de configuração clusterctl incorporados (config-community.yaml / config-prime.yaml) para a lista completa de imagens de provedores que precisam ser espelhadas.

SUSE® Rancher Prime Cluster API inclui um recurso alpha, use-rancher-default-registry, que simplifica a gestão de imagens em ambientes air-gapped. Quando habilitado (o padrão), SUSE® Rancher Prime Cluster API lê a configuração de gerenciamento system-default-registry do Rancher e automaticamente prefixa todos os repositórios de imagens dos provedores CAPI com o registro configurado.

Sem esse recurso, as imagens dos provedores que referenciam registros externos, como registry.k8s.io, não são acessíveis em um cluster air-gapped. O pipeline de espelhamento de imagens do Rancher espelha imagens de upstream, mas apenas a parte do registro de uma referência de imagem é tipicamente substituível - não o nome da imagem em si. Isso pode levar a incompatibilidades quando as imagens espelhadas usam uma convenção de nomenclatura diferente (por exemplo, rancher/mirrored-cluster-api-controller em vez de cluster-api/cluster-api-controller), ou quando certas imagens (por exemplo, registry.k8s.io/kubernetes/kubectl) não são espelhadas de forma alguma.

Com use-rancher-default-registry habilitado, SUSE® Rancher Prime Cluster API resolve isso lendo a configuração de gerenciamento system-default-registry do Rancher e usando seu valor para reescrever todos os repositórios de imagens dos provedores. A configuração clusterctl-config incorporada ConfigMap serve como a fonte de verdade para quais provedores e imagens são suportados. Se a configuração estiver vazia, SUSE® Rancher Prime Cluster API recorre às referências de imagem padrão.

Como funciona

SUSE® Rancher Prime Cluster API lê a configuração de gerenciamento system-default-registry do Rancher.
Se a configuração contiver uma URL de registro não vazia, SUSE® Rancher Prime Cluster API itera por todas as imagens de provedores definidas na configuração clusterctl incorporada.
Para cada imagem, o prefixo do registro original é removido e substituído pelo valor de system-default-registry, preservando o namespace e o nome da imagem.

Por exemplo, registry.k8s.io/cluster-api/cluster-api-controller se torna my-registry.example.com/cluster-api/cluster-api-controller.
Quaisquer substituições de imagem especificadas no recurso ClusterctlConfig são aplicadas após o prefixo do registro, permitindo substituições seletivas por imagem.

Substituições de imagem definidas no recurso ClusterctlConfig sempre têm precedência. Se uma imagem de provedor específica for configurada via ClusterctlConfig, ela substitui o valor prefixado do registro. Isso fornece um mecanismo para substituir seletivamente imagens específicas enquanto se baseia no prefixo automático do registro para o restante.

Habilitando ou desabilitando

Esse recurso está habilitado por padrão. Para desabilitá-lo e voltar às referências de imagem originais, defina o seguinte em seus valores do Helm:

features:
  use-rancher-default-registry:
    enabled: false

Instalação do provedor CAPI com artefato OCI

Como administrador trabalhando em um ambiente air-gapped, você precisa buscar os componentes do provedor CAPI dentro do seu cluster, uma vez que o acesso à internet externa é restrito. Esta seção demonstra como implantar provedores CAPI usando artefatos OCI.

Usuários Prime

Como usuário do Rancher Prime, você pode espelhar diretamente artefatos OCI de provedores pré-validados do Registro do Rancher Prime para seu registro privado.

Defina a URL do seu registro privado:

export REGISTRY=<YOUR_PRIVATE_REGISTRY>

Espelhe o provedor do Registro do Rancher Prime para seu registro privado. Consulte config-prime.yaml para as versões exatas dos provedores disponíveis para sua versão do Turtles.

Por exemplo, para usar o provedor Azure:

# Set the version from config-prime.yaml
export PROVIDER_VERSION=<VERSION_FROM_CONFIG_PRIME>

# Pull from Rancher Prime Registry
oras pull registry.rancher.com/rancher/cluster-api-azure-controller-components:${PROVIDER_VERSION}

# Push to your private registry
oras push ${REGISTRY}/cluster-api-azure-controller-components:${PROVIDER_VERSION} infrastructure-components.yaml:application/vnd.test.file metadata.yaml:application/vnd.test.file

Crie e aplique o recurso CAPIProvider apontando para seu registro privado:

capz-provider-oci.yaml

apiVersion: turtles-capi.cattle.io/v1alpha1
kind: CAPIProvider
metadata:
  name: azure
  namespace: capz-system
spec:
  type: infrastructure
  name: azure
  version: ${PROVIDER_VERSION}
  fetchConfig:
    oci: ${REGISTRY}/cluster-api-azure-controller-components:${PROVIDER_VERSION}

Como espelhar artefato OCI do provedor CAPI

Esta seção mostra como espelhar artefatos OCI do provedor CAPI para seu registro privado para uso em um ambiente air-gapped.

Usuários Prime

Como usuário do Rancher Prime, você pode espelhar artefatos OCI pré-validados do provedor CAPI do Rancher Prime Registry. Verifique config-prime.yaml para provedores disponíveis e suas versões para sua versão do Turtles.

Instale a ferramenta de linha de comando ORAS (OCI Registry As Storage) para gerenciar artefatos OCI. Siga as instruções de instalação em: https://oras.land/docs/installation.

Defina a URL do seu registro privado e a versão do provedor:

export REGISTRY=<YOUR_PRIVATE_REGISTRY>
export PROVIDER_VERSION=<VERSION_FROM_CONFIG_PRIME>

Crie o diretório de trabalho:

mkdir capi-oci-artifacts
cd capi-oci-artifacts

Baixe o artefato OCI do Registro do Rancher Prime. Por exemplo, para o provedor Azure:

oras pull registry.rancher.com/rancher/cluster-api-azure-controller-components:${PROVIDER_VERSION}

Publique o artefato OCI em seu registro privado:

oras push ${REGISTRY}/cluster-api-azure-controller-components:${PROVIDER_VERSION} infrastructure-components.yaml:application/vnd.test.file metadata.yaml:application/vnd.test.file

Crie e aplique o recurso CAPIProvider:

capz-provider-oci.yaml

apiVersion: turtles-capi.cattle.io/v1alpha1
kind: CAPIProvider
metadata:
  name: azure
  namespace: capz-system
spec:
  type: infrastructure
  name: azure
  version: ${PROVIDER_VERSION}
  fetchConfig:
    oci: ${REGISTRY}/cluster-api-azure-controller-components:${PROVIDER_VERSION}

Use kubectl para criar o namespace e aplicar a configuração:

kubectl create namespace capz-system
kubectl apply -f capz-provider-oci.yaml

CAPI Provider busca e publica artefato OCI

Esta seção demonstra como construir e publicar artefatos OCI a partir do código-fonte. Isso é principalmente útil para usuários da Comunidade que desejam construir provedores por conta própria ou personalizar versões de provedores. Usuários Prime geralmente não precisam desse fluxo de trabalho, pois podem usar artefatos pré-espelhados do Rancher Prime Registry.

Usando o operador kubectl
Usando Oras

Você pode construir artefatos OCI para qualquer Provedor CAPI listado na configuração SUSE® Rancher Prime Cluster API: https://github.com/rancher/turtles/blob/main/internal/controllers/clusterctl/config-community.yaml

Instale o plugin cluster-api-operator para kubectl.

Clone o repositório oficial Azure CAPI Provider e navegue até o diretório do projeto.

git clone https://github.com/kubernetes-sigs/cluster-api-provider-azure/
cd cluster-api-provider-azure

Escolha a versão específica que deseja implantar. Você pode listar todas as tags disponíveis,

Não há versão latest no cenário OCI, portanto, a versão precisa ser definida o tempo todo.

git tag

ou selecionar automaticamente a versão mais recente:

export RELEASE_TAG=`git describe --abbrev=0`

Defina a URL do seu registro privado e substitua pela sua URL real:

export PROD_REGISTRY=<YOUR_PRIVATE_REGISTRY>

Construa os artefatos de lançamento infrastructure-components.yaml e metadata.yaml:

make release

Vá para o diretório de saída que contém os artefatos:

cd out

Crie e publique um artefato OCI contendo os manifests do Azure CAPIProvider no seu registro privado:

kubectl operator publish -u ${PROD_REGISTRY}:${RELEASE_TAG} infrastructure-components.yaml metadata.yaml

Você pode construir artefatos OCI para qualquer CAPIProvider listado na configuração SUSE® Rancher Prime Cluster API: https://github.com/rancher/turtles/blob/main/internal/controllers/clusterctl/config-community.yaml

Clone o repositório oficial Azure CAPIProvider repositório e navegue até o diretório do projeto.

git clone https://github.com/kubernetes-sigs/cluster-api-provider-azure/
cd cluster-api-provider-azure

Escolha a versão específica que deseja implantar. Você pode listar todas as tags disponíveis,

Não há versão latest no cenário OCI, portanto, a versão precisa ser definida o tempo todo.

git tag

ou selecionar automaticamente a versão mais recente:

export RELEASE_TAG=`git describe --abbrev=0`

Defina a URL do seu registro privado e substitua pela sua URL real:

export PROD_REGISTRY=<YOUR_PRIVATE_REGISTRY>

Construa os artefatos de lançamento infrastructure-components.yaml e metadata.yaml:

make release

Vá para o diretório de saída que contém os artefatos:

cd out

Instale a CLI ORAS (OCI Registry As Storage) para gerenciar artefatos OCI. Siga as instruções de instalação em: https://oras.land/docs/installation

Crie e publique um artefato OCI contendo os manifests do Azure CAPIProvider no seu registro privado:

oras push ${PROD_REGISTRY}:${RELEASE_TAG} infrastructure-components.yaml:application/vnd.test.file metadata.yaml:application/vnd.test.file

Crie e aplique o recurso Azure CAPIProvider que instrui SUSE® Rancher Prime Cluster API a buscar o provedor Azure do seu registro OCI privado:

capz-provider-oci.yaml

apiVersion: turtles-capi.cattle.io/v1alpha1
kind: CAPIProvider
metadata:
  name: azure
  namespace: capz-system
spec:
  type: infrastructure
  name: azure
  version: ${RELEASE_TAG}
  fetchConfig:
    oci: ${PROD_REGISTRY}:${RELEASE_TAG}

Use kubectl para criar o namespace capz-system e aplique o arquivo capz-provider-oci.yaml ao cluster:

kubectl apply -f capz-provider-oci.yaml

Instalação do CAPIProvider com manifest obtido

Esta seção demonstra uma abordagem alternativa para instalações air-gapped usando ConfigMaps em vez de artefatos OCI. Este método funciona tanto para usuários da Community quanto para usuários da Prime e pode ser útil quando o acesso ao registro OCI é limitado ou quando você prefere gerenciar os manifests do provedor diretamente.

Como administrador, você precisa buscar os componentes do provedor vSphere (CAPV) de dentro do cluster porque está trabalhando em um ambiente air-gapped.

Neste exemplo, há um ConfigMap no namespace capv-system que define os componentes e metadados do provedor. Ele pode ser criado manualmente ou executando os seguintes comandos:

# Get the file contents from the GitHub release
curl -L https://github.com/rancher-sandbox/cluster-api-provider-vsphere/releases/download/v1.12.0/infrastructure-components.yaml -o components.yaml
curl -L https://github.com/rancher-sandbox/cluster-api-provider-vsphere/releases/download/v1.12.0/metadata.yaml -o metadata.yaml

# Create the configmap from the files
kubectl create configmap v1.12.0 --namespace=capv-system --from-file=components=components.yaml --from-file=metadata=metadata.yaml --dry-run=client -o yaml > configmap.yaml

Este exemplo de comando precisará ser adaptado ao provedor e à versão que você deseja usar. O mapa de configuração resultante será semelhante ao exemplo abaixo:

apiVersion: v1
kind: ConfigMap
metadata:
  labels:
    provider-components: vsphere
  name: v1.12.0
  namespace: capv-system
data:
  components: |
    # Components for v1.12.0 YAML go here
  metadata: |
    # Metadata information goes here

Um recurso CAPIProvider precisará ser criado para representar o provedor de infraestrutura vSphere. Ele precisará ser configurado com um fetchConfig. O seletor de rótulos permite que o operador determine as versões disponíveis do provedor vSphere e os recursos do Kubernetes que precisam ser implantados (ou seja, contidos em ConfigMaps que correspondem ao seletor de rótulos).

Como a versão do provedor está marcada como v1.12.0, o operador usa as informações dos componentes do ConfigMap com rótulo correspondente para instalar o provedor vSphere.

apiVersion: turtles-capi.cattle.io/v1alpha1
kind: CAPIProvider
metadata:
  name: vsphere
  namespace: capv-system
spec:
  name: vsphere
  type: infrastructure
  version: v1.12.0
  configSecret:
    name: vsphere-variables
  fetchConfig:
    selector:
      matchLabels:
        provider-components: vsphere
  deployment:
    containers:
    - name: manager
      imageUrl: "registry.suse.com/rancher/cluster-api-vsphere-controller:v1.12.0"
  variables:
    CLUSTER_TOPOLOGY: "true"
    EXP_CLUSTER_RESOURCE_SET: "true"
    EXP_MACHINE_POOL: "true"

Além disso, o CAPIProvider substitui a imagem do contêiner a ser usada para o provedor usando o campo deployment.containers[].imageUrl. Isso permite que o operador puxe a imagem de um registro dentro do ambiente air-gapped.

Limitações de tamanho do ConfigMap

Há um limite para o tamanho máximo de um ConfigMap - 1MiB. Se os manifests não couberem nesse tamanho, o Kubernetes gerará um erro e a instalação do provedor falhará. Para evitar isso, você pode arquivar os manifests e colocá-los no ConfigMap dessa forma.

Por exemplo, você tem dois arquivos: components.yaml e metadata.yaml. Para criar um mapa de configuração funcional, você precisa:

Arquivar components.yaml usando a CLI gzip
```
gzip -c components.yaml > components.gz
```

Criar um manifesto de ConfigMap a partir dos dados arquivados

kubectl create configmap v1.12.0 --namespace=capv-system --from-file=components=components.gz --from-file=metadata=metadata.yaml --dry-run=client -o yaml > configmap.yaml

Editar o arquivo adicionando a anotação "provider.cluster.x-k8s.io/compressed: true"
```
yq eval -i '.metadata.annotations += {"provider.cluster.x-k8s.io/compressed": "true"}' configmap.yaml
```
Sem essa anotação, o operador não conseguirá determinar se os dados estão comprimidos ou não.
Adicionar rótulos que serão usados para corresponder ao ConfigMap na seção fetchConfig do provedor
```
yq eval -i '.metadata.labels += {"my-label": "label-value"}' configmap.yaml
```
Criar um ConfigMap em seu cluster Kubernetes usando kubectl
```
kubectl create -f configmap.yaml
```