Use Resource Overrides para personalizar recursos implementados pelo Azure Kubernetes Fleet Manager resource placement

Aplica-se a: ✔️ Fleet Manager com cluster de hub

O Azure Kubernetes Fleet Manager Smart Resource placement pode implementar o mesmo recurso em múltiplos clusters numa frota. Muitas vezes, é preciso modificar a configuração dos recursos para impor regras de comportamento em diferentes ambientes (dev, test, prod). Para este efeito, o Fleet Manager disponibiliza redefinições de recursos, que proporcionam uma capacidade conceptualmente semelhante à forma como os modelos do Helm e os patches do Kustomize são utilizados.

Modificar uma configuração de recurso é útil em situações como:

  • Queres usar um ClusterRole nome secret-reader em todos os clusters, mas ter um conjunto menor de ações permitidas para a função nos clusters de produção.
  • Queres usar o mesmo Deployment em todos os clusters, mas usa uma imagem de contentor ou porta diferente nos clusters de produção.

Este artigo mostra-lhe como criar sobreposições para recursos implementados pelo Fleet Manager resource placement.

Azure Kubernetes Fleet Manager suporta dois escopos para sobrescrições:

  • Âmbito cluster: Uso ClusterResourceOverride com ClusterResourcePlacement para administradores de frotas que gerem alterações ao nível da infraestrutura.
  • Namespace-scoped: Uso ResourceOverride com ResourcePlacement para equipas de aplicações que gerem implementações dentro dos seus namespaces específicos.

Selecione o âmbito mais adequado a si entre as opções de tipos de âmbito no topo do artigo.

Sobreposições de recursos de âmbito de cluster

A ClusterResourceOverride tem as seguintes propriedades:

  • placement (opcional): Especifica a que ClusterResourcePlacement a substituição está associada.
  • clusterResourceSelectors: Especifica o conjunto de recursos do cluster selecionados para substituição.
  • policy: Especifica o conjunto de regras a aplicar aos recursos selecionados do cluster.

Importante

Se não especificares um placement, o override aplica-se a quaisquer recursos que correspondam ao clusterResourceSelectors e que qualquer ClusterResourcePlacement implemente. Esta condição pode ter consequências não intencionais nos recursos e no desempenho global da implementação, por isso defina um posicionamento.

O exemplo ClusterRole seguinte, chamado secret-reader, demonstra como ClusterResourceOverride funciona.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: secret-reader
rules:
- apiGroups: [""]
  resources: ["secrets"]
  verbs: ["get", "watch", "list"]

Seleção de recursos de cluster

A ClusterResourceOverride pode incluir um ou mais clusterResourceSelector para escolher quais recursos substituir. Cada um clusterResourceSelector suporta os seguintes campos.

  • group: O grupo API do recurso.
  • version: A versão API do recurso.
  • kind: O tipo de recurso.
  • name: O nome do recurso.

Observação

Se selecionar um namespace em ClusterResourceSelector, a substituição aplica-se a todos os recursos no namespace.

Usando o nosso exemplo ClusterRole, vamos ver como o selecionamos num ClusterResourceOverride.

apiVersion: placement.kubernetes-fleet.io/v1
kind: ClusterResourceOverride
metadata:
  name: example-cro
spec:
  placement:
    name: sample-placement
  clusterResourceSelectors:
    - group: rbac.authorization.k8s.io
      kind: ClusterRole
      version: v1
      name: secret-reader

Substituições de recursos ao nível do espaço de nomes

A ResourceOverride tem as seguintes propriedades:

  • placement (opcional): Especifica a que ResourcePlacement a substituição está associada.
  • resourceSelectors: Especifica o conjunto de recursos selecionados para substituição.
  • policy: Especifica o conjunto de regras a aplicar aos recursos selecionados.

Importante

Se não especificar um placement, a sobreposição aplica-se a quaisquer recursos que correspondam ao resourceSelectors e que qualquer ResourcePlacement no mesmo namespace implemente. Esta condição pode ter consequências não intencionais nos recursos e no desempenho global da implementação, por isso defina um posicionamento.

Para demonstrar como ResourceOverride funciona, use o seguinte exemplo Deployment chamado nginx-sample.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-sample
  namespace: nginx-demo
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.25
          ports:
            - containerPort: 80

Selecionar recursos do espaço de nomes

A ResourceOverride pode incluir um ou mais resourceSelector para escolher quais recursos substituir. Cada um resourceSelector suporta os seguintes campos:

  • group: O grupo API do recurso.
  • version: A versão API do recurso.
  • kind: O tipo de recurso.
  • name: O nome do recurso.

Determina-se o namespace do recurso a substituir especificando o conjunto namespace em metadata de ResourceOverride.

Usando o exemplo Deployment, pode ver como selecioná-lo num ResourceOverride.

apiVersion: placement.kubernetes-fleet.io/v1
kind: ResourceOverride
metadata:
  name: example-resource-override
  namespace: nginx-demo
spec:
  placement:
    name: sample-placement
  resourceSelectors:
    -  group: apps
       kind: Deployment
       version: v1
       name: nginx-sample

Importante

  • Se selecionares um namespace em resourceSelector (kind: Namespace), a sobreposição aplica-se a todos os recursos no namespace.
  • O ResourceOverride precisa estar no mesmo espaço de nomes do recurso a substituir.

Agora que selecionou o recurso, vamos ver como configurar a substituição usando um policy.

Policy

A policy consiste num conjunto de overrideRules que especificam as alterações a aplicar aos recursos selecionados. Cada um overrideRules suporta os seguintes campos:

  • clusterSelector: Especifica o conjunto de clusters a que a regra de sobreposição se aplica.
  • jsonPatchOverrides: Especifica as alterações a aplicar aos recursos selecionados.

Seletor de cluster

Use o clusterSelector campo em overrideRules para especificar os clusters a que a regra se aplica. Suporta clusterSelector o seguinte campo:

  • clusterSelectorTerms: Uma lista de termos que especificam os critérios de seleção dos clusters. Cada termo inclui um labelSelector campo que define um conjunto de rótulos a corresponder.

Importante

Só labelSelector é suportado no clusterSelectorTerms campo.

Substituições de patches JSON

Use jsonPatchOverrides in overrideRules para especificar as alterações a aplicar aos recursos selecionados. A JsonPatch propriedade suporta os seguintes campos:

  • op: A operação a realizar. As operações apoiadas incluem:

    • add: Adiciona um novo valor ao caminho especificado.
    • remove: Remove o valor no caminho especificado.
    • replace: Substitui o valor no caminho especificado.
  • path: O caminho para o campo a modificar. As orientações para especificar caminhos incluem:

    • Tem de começar com uma personagem slash (/).
    • Não pode estar vazio nem conter uma cadeia vazia.
    • Não pode ser um TypeMeta campo (/kind ou /apiVersion).
    • Não pode ser um Metadata corpo (/metadata/name ou /metadata/namespace), exceto os campos /metadata/labels e /metadata/annotations.
    • Não pode haver nenhum campo no estado do recurso.

    Exemplos de caminhos válidos incluem:

    • /metadata/labels/new-label
    • /metadata/annotations/new-annotation
    • /spec/template/spec/containers/0/resources/limits/cpu
    • /spec/template/spec/containers/0/resources/requests/memory
  • value: O valor a acrescentar, remover ou substituir. Se op estiver remove, não pode especificar value.

Os jsonPatchOverrides campos aplicam um patch JSON nos recursos selecionados seguindo o RFC 6902.

Estendendo o nosso exemplo, configura uma policy para remover o verbo list do ClusterRole denominado secret-reader em clusters rotulados com env:prod.

apiVersion: placement.kubernetes-fleet.io/v1
kind: ClusterResourceOverride
metadata:
  name: example-cro
spec:
  placement:
    name: sample-placement
  clusterResourceSelectors:
    - group: rbac.authorization.k8s.io
      kind: ClusterRole
      version: v1
      name: secret-reader
  policy:
    overrideRules:
      - clusterSelector:
          clusterSelectorTerms:
            - labelSelector:
                matchLabels:
                  env: prod
        jsonPatchOverrides:
          - op: remove
            path: /rules/0/verbs/2

Estendendo o nosso exemplo, configura-se policy para substituir a imagem do contentor em Deployment pela imagem nginx:1.30.0 nos clusters com o rótulo env: prod.

apiVersion: placement.kubernetes-fleet.io/v1
kind: ResourceOverride
metadata:
  name: example-resource-override
  namespace: nginx-demo
spec:
  placement:
    name: sample-placement
  resourceSelectors:
    -  group: apps
       kind: Deployment
       version: v1
       name: test-nginx
  policy:
    overrideRules:
      - clusterSelector:
          clusterSelectorTerms:
            - labelSelector:
                matchLabels:
                  env: prod
        jsonPatchOverrides:
          - op: replace
            path: /spec/template/spec/containers/0/image
            value: "nginx:1.30.0"

Defina múltiplas substituições

Adicione vários campos jsonPatchOverrides a overrideRules para aplicar várias alterações aos recursos do cluster selecionados. Aqui está um exemplo:

Este exemplo remove os verbos list e watch no exemplo ClusterRole nomeado secret-reader em agrupamentos com o rótulo env: prod.

apiVersion: placement.kubernetes-fleet.io/v1
kind: ClusterResourceOverride
metadata:
  name: cro-1
spec:
  placement:
    name: sample-placement
  clusterResourceSelectors:
    - group: rbac.authorization.k8s.io
      kind: ClusterRole
      version: v1
      name: secret-reader
  policy:
    overrideRules:
      - clusterSelector:
          clusterSelectorTerms:
            - labelSelector:
                matchLabels:
                  env: prod
        jsonPatchOverrides:
          - op: remove
            path: /rules/0/verbs/2
          - op: remove
            path: /rules/0/verbs/1

Este exemplo substitui tanto a imagem do contentor como a porta no Deployment com 443 para clusters com o rótulo env: prod.

apiVersion: placement.kubernetes-fleet.io/v1
kind: ResourceOverride
metadata:
  name: example-resource-override
  namespace: nginx-demo
spec:
  placement:
    name: sample-placement
  resourceSelectors:
    -  group: apps
       kind: Deployment
       version: v1
       name: test-nginx
  policy:
    overrideRules:
      - clusterSelector:
          clusterSelectorTerms:
            - labelSelector:
                matchLabels:
                  env: prod
        jsonPatchOverrides:
          - op: replace
            path: /spec/template/spec/containers/0/image
            value: "nginx:1.30.0"
          - op: replace
            path: /spec/template/spec/containers/0/ports/0/containerPort
            value: "443"

Variáveis reservadas no valor de override do patch JSON

O value da regra de substituição do patch JSON substitui as variáveis reservadas no momento da inserção. Variáveis reservadas atualmente suportadas:

  • ${MEMBER-CLUSTER-NAME}: substituída pelo nome do memberCluster.

Por exemplo, para criar um nome de anfitrião do DNS do Azure que contenha o nome do cluster, o exemplo ResourceOverride adiciona um valor de fleet-clustername-eastus nos clusters na região do Azure eastus.

apiVersion: placement.kubernetes-fleet.io/v1
kind: ResourceOverride
metadata:
  name: ro-kuard-demo-eastus
  namespace: kuard-demo
spec:
  placement:
    name: crp-kuard-demo
  resourceSelectors:
    -  group: ""
        kind: Service
        version: v1
        name: kuard-svc
  policy:
    overrideRules:
      - clusterSelector:
          clusterSelectorTerms:
            - labelSelector:
                matchLabels:
                  fleet.azure.com/location: eastus
        jsonPatchOverrides:
          - op: add
            path: /metadata/annotations
            value:
              {"service.beta.kubernetes.io/azure-dns-label-name":"fleet-${MEMBER-CLUSTER-NAME}-eastus"}

Regras de substituição múltipla

Adicione múltiplos overrideRules a um policy campo para aplicar múltiplas alterações aos recursos selecionados. Aqui está um exemplo para ResourceOverride.

Este exemplo substitui a imagem do contentor em o Deployment por:

  • A imagem nginx:1.20.0 para os agrupamentos com o rótulo env: prod.
  • A imagem nginx:latest para os agrupamentos com o rótulo env: test.
apiVersion: placement.kubernetes-fleet.io/v1
kind: ResourceOverride
metadata:
  name: ro-1
  namespace: test
spec:
  placement:
    name: sample-placement
  resourceSelectors:
    -  group: apps
       kind: Deployment
       version: v1
       name: test-nginx
  policy:
    overrideRules:
      - clusterSelector:
          clusterSelectorTerms:
            - labelSelector:
                matchLabels:
                  env: prod
        jsonPatchOverrides:
          - op: replace
            path: /spec/template/spec/containers/0/image
            value: "nginx:1.20.0"
      - clusterSelector:
          clusterSelectorTerms:
            - labelSelector:
                matchLabels:
                  env: test
        jsonPatchOverrides:
          - op: replace
            path: /spec/template/spec/containers/0/image
            value: "nginx:latest"

Utilização com colocação de recursos em clusters

  1. Crie a ClusterResourcePlacement para especificar as regras de posicionamento para a distribuição dos sobrescritos de recursos do cluster pela infraestrutura do cluster. O código seguinte é um exemplo. Certifique-se de escolher o recurso apropriado.

    apiVersion: placement.kubernetes-fleet.io/v1
    kind: ClusterResourcePlacement
    metadata:
      name: crp
    spec:
      resourceSelectors:
        - group: rbac.authorization.k8s.io
          kind: ClusterRole
          version: v1
          name: secret-reader
      policy:
        placementType: PickAll
        affinity:
          clusterAffinity:
            requiredDuringSchedulingIgnoredDuringExecution:
              clusterSelectorTerms:
                - labelSelector:
                    matchLabels:
                      env: prod
    

    Este exemplo distribui recursos entre todos os clusters rotulados com env: prod. À medida que implementas as alterações, as configurações correspondentes ClusterResourceOverride aplicam-se aos clusters designados. A seleção de um recurso correspondente ao papel do cluster, secret-reader, desencadeia a aplicação das configurações aos clusters.

  2. Aplica o ClusterResourcePlacement usando o kubectl apply comando:

    kubectl apply -f cluster-resource-placement.yaml
    
  3. Verifique se o ClusterResourceOverride foi aplicado aos recursos selecionados verificando o estado do ClusterResourcePlacement recurso através do kubectl describe comando:

    kubectl describe clusterresourceplacement crp
    

    A sua saída deve assemelhar-se ao seguinte exemplo:

    Status:
      Conditions:
        ...
        Last Transition Time:   2024-04-27T04:18:00Z
        Message:                The selected resources are successfully overridden in the 10 clusters
        Observed Generation:    1
        Reason:                 OverriddenSucceeded
        Status:                 True
        Type:                   ClusterResourcePlacementOverridden
        ...
      Observed Resource Index:  0
      Placement Statuses:
        Applicable Cluster Resource Overrides:
          example-cro-0
        Cluster Name:  member-50
        Conditions:
          ...
          Message:               Successfully applied the override rules on the resources
          Observed Generation:   1
          Reason:                OverriddenSucceeded
          Status:                True
          Type:                  Overridden
         ...
    

    A ClusterResourcePlacementOverridden condição indica se a sobreposição de recursos foi aplicada com sucesso aos recursos selecionados nos clusters. Cada cluster mantém a sua própria Applicable Cluster Resource Overrides lista. Esta lista contém uma captura da modificação de recursos do cluster, se for relevante. Mensagens de estado individuais para cada cluster indicam se as regras de sobreposição foram aplicadas com sucesso.

Uso com alocação de recursos

  1. Crie um ClusterResourcePlacement recurso para especificar as regras de colocação para distribuir os overrides de recursos na infraestrutura do cluster. O código seguinte é um exemplo. Certifique-se de selecionar os namespaces apropriados.

    apiVersion: placement.kubernetes-fleet.io/v1
    kind: ClusterResourcePlacement
    metadata:
      name: crp-example
    spec:
      resourceSelectors:
        - group: ""
          kind: Namespace
          name: test-namespace
          version: v1
      policy:
        placementType: PickAll
        affinity:
          clusterAffinity:
            requiredDuringSchedulingIgnoredDuringExecution:
              clusterSelectorTerms:
                - labelSelector:
                    matchLabels:
                      env: prod
                - labelSelector:
                    matchLabels:
                      env: test
    

    Este exemplo distribui recursos dentro test-namespace de todos os clusters rotulados com env:prod e env:test. À medida que as alterações são implementadas, as configurações correspondentes ResourceOverride aplicam-se aos recursos designados. A seleção de um recurso de implementação correspondente, my-deployment, desencadeia a aplicação das configurações aos recursos designados.

  2. Aplique o ClusterResourcePlacement recurso usando o kubectl apply comando:

    kubectl apply -f cluster-resource-placement.yaml
    
  3. Verifique se o ResourceOverride foi aplicado aos recursos selecionados verificando o estado do ClusterResourcePlacement recurso através do kubectl describe comando:

    kubectl describe clusterresourceplacement crp-example
    

    A sua saída deve assemelhar-se ao seguinte exemplo:

    Status:
      Conditions:
        ...
        Message:                The selected resources are successfully overridden in the 10 clusters
        Observed Generation:    1
        Reason:                 OverriddenSucceeded
        Status:                 True
        Type:                   ClusterResourcePlacementOverridden
        ...
      Observed Resource Index:  0
      Placement Statuses:
        Applicable Resource Overrides:
          Name:        ro-1-0
          Namespace:   test-namespace
        Cluster Name:  member-50
        Conditions:
          ...
          Last Transition Time:  2024-04-26T22:57:14Z
          Message:               Successfully applied the override rules on the resources
          Observed Generation:   1
          Reason:                OverriddenSucceeded
          Status:                True
          Type:                  Overridden
         ...
    

    A ClusterResourcePlacementOverridden condição indica se a sobreposição de recursos foi aplicada com sucesso aos recursos selecionados. Cada cluster mantém a sua própria Applicable Resource Overrides lista. Esta lista contém o instantâneo de sobreposição de recursos, se relevante. Mensagens de estado individuais para cada cluster indicam se as regras de sobreposição foram aplicadas com sucesso.