Ignorar campos não especificados

---

Este documento explica como mudar os campos de especificação padrão preenchendo o comportamento usando a anotação cnrm.cloud.google.com/state-into-spec e quando você precisa mudar isso.

Conforme explicado em Gerenciar campos externamente, quando o Config Connector cria um recurso no Google Cloud, os campos deixados não especificados na especificação aceitam valores da API, a menos que não sejam legíveis (por exemplo, não estão disponíveis usando uma solicitação HTTP GET).

Isso significa, por padrão, campos que não foram especificados no YAML original que sempre aparecem na especificação do recurso do Kubernetes. Isso significa que, quando você fizer kubectl get <resource kind> <resource name> -oyaml, muitos campos na especificação do recurso não estarão no YAML aplicado.

Por exemplo, suponha que o esquema do CRD permita especificar dois campos chamados foo e bar na especificação, enquanto o arquivo YAML aplicado tem apenas foo especificado:

spec:
  foo: "foo"

Você verá outro campo chamado bar no recurso do Kubernetes se o YAML for aplicado e o recurso for UpToDate:

spec:
  foo: "foo"
  bar: "bar"

Devido à complexidade da interação entre o Config Connector e as APIs do Google Cloud, talvez você queira mudar esse comportamento padrão e pular o preenchimento da especificação de recursos com campos não especificados.

Pular o preenchimento de campos não especificados na especificação

Ao criar o arquivo YAML, é possível especificar o valor da anotação cnrm.cloud.google.com/state-into-spec como absent. Isso pula o preenchimento de campos não especificados para a especificação de recursos do Kubernetes:

metadata:
  annotations:
    cnrm.cloud.google.com/state-into-spec: absent

Essa anotação tem um valor padrão de merge se não for especificado, o que significa que o Config Connector preenche todos os campos não especificados na especificação. Essa anotação é imutável, o que significa que não é possível atualizar o valor da anotação de um recurso atual do Config Connector.

Se você já criou o recurso, mas quer alterar o valor dessa anotação para um comportamento de preenchimento diferente, siga estas etapas:

1. Edite e adicione a anotação cnrm.cloud.google.com/deletion-policy: abandon ao recurso do Kubernetes para garantir que a exclusão na próxima etapa não excluirá o recurso subjacente do Google Cloud.

2. Exclua o recurso do cluster do Kubernetes.

3. Adicione a anotação cnrm.cloud.google.com/state-into-spec: absent ao YAML do recurso.

4. (Opcional) Remova cnrm.cloud.google.com/deletion-policy: abandon do YAML.

5. Aplique o YAML atualizado.

Para explicar a diferença introduzida por essa anotação, suponha que haja uma especificação com o esquema abaixo:

foo1: string
foo2: string
bars:
- bar:
    br1: string
    br2: string
barz:
  bz1: string
  bz2: string

Suponha também que você tenha especificado a especificação no YAML como:

spec:
  foo1: "foo1"
  bars:
  - br1: "1_br1"
  - br1: "2_br1"
  barz:
    bz1: "bz1"

Por padrão, a especificação preenchida no recurso do Kubernetes criado pode ser:

spec:
  foo1: "foo1"
  foo2: "foo2"
  bars:
  - br1: "1_br1"
    br2: "1_br2"
  - br1: "2_br1"
    br2: "2_br2"
  barz:
    bz1: "bz1"
    bz2: "bz2"

Se você definir cnrm.cloud.google.com/state-into-spec: absent, a especificação final no recurso do Kubernetes criado será:

spec:
  foo1: "foo1"
  bars:
  - br1: "1_br1"
  - br1: "2_br1"
  barz:
    bz1: "bz1"

Quando usar cnrm.cloud.google.com/state-into-spec: absent

Em alguns cenários comuns, é possível definir cnrm.cloud.google.com/state-into-spec: absent.

Gerenciar campos não especificados em uma lista externamente

O Config Connector trata todos os campos de lista na especificação do recurso como campos atômicos. Como resultado, por padrão, a alteração feita em um subcampo na lista de fora do Config Connector será revertida pelo Config Connector. No entanto, você pode usar essa anotação para permitir que o Config Connector cancele o gerenciamento de subcampos na lista. Para mais informações, consulte Comportamento para campos de lista na especificação de recursos.

Resolver o conflito entre as ferramentas de gerenciamento de configuração e o Config Connector

Se você estiver usando ferramentas de gerenciamento de configuração, como o Config Sync ou o Argo CD, perceberá uma luta entre a ferramenta de gerenciamento de configuração e o Config Connector. Um exemplo é o erro KNV2005 explicado no guia de solução de problemas. A causa desses problemas é que:

1. O Config Connector preencherá os valores não especificados na lista na especificação, e spec.bars[0].br2 é um exemplo.
2. As ferramentas de gerenciamento de configuração e o Config Connector tratam os campos de lista como atômicos. Dessa forma, o spec.bars[0].br2 adicionado é tratado como um deslocamento pelas ferramentas de gerenciamento de configuração e vai ser removido para corrigir o drift.

Para resolver esses problemas, defina cnrm.cloud.google.com/state-into-spec: absent para que o Config Connector não adicione o campo spec.bars[0].br2 não especificado à especificação.

Resolver problemas de simetria GET/PUT

A simetria GET/PUT se refere a um princípio de design na API REST. Ou seja, quando uma resposta GET é enviada como uma solicitação PUT para o mesmo URL, o resultado esperado é uma resposta HTTP 200 OK sem alterações no estado do recurso REST subjacente.

Os campos não especificados preenchidos pelo Config Connector na especificação do recurso são como resultado de uma solicitação GET. Isso significa que, em reconciliações futuras, o Config Connector poderá enviar uma solicitação PUT/PATCH para a API Google Cloud subjacente, com esses valores de campo não especificados aprendidos com a solicitação GET. Isso geralmente não é um problema, mas é possível que algumas APIs do Google Cloud rejeitem a solicitação PUT/PATCH devido a esses valores de campo não especificados. No mesmo exemplo, o spec.barz.bz2 preenchido com valor "bz2" pode resultar em um erro de cliente HTTP 400 ou em outras respostas inesperadas se a implementação da API violar o princípio da simetria GET/PUT.

Para evitar essa categoria de problemas, tente definir cnrm.cloud.google.com/state-into-spec: absent e verificar se os erros durante a reconciliação vão desaparecer.

Quando evitar cnrm.cloud.google.com/state-into-spec: absent

Evite configurar cnrm.cloud.google.com/state-into-spec: absent se a solução depender dos valores preenchidos de campos não especificados. Por exemplo, se você estiver usando um recurso ComputeAddress e precisar do valor spec.address gerado pelo servidor, que pode ser um campo não especificado no YAML original, não use essa anotação, porque ela vai ignorar o valor de spec.address na especificação de recurso do Kubernetes.