As definições de recursos personalizados (CRDs, na sigla em inglês) são ferramentas poderosas para estender os recursos do Kubernetes.
No entanto, se uma CRD contiver um pacote de autoridade de certificação (CA) inválido ou malformado na configuração do webhook de conversão spec.conversion.webhook.clientConfig.caBundle, isso poderá interromper as operações do cluster. Isso pode se manifestar como erros durante a criação, atualização ou
exclusão de recursos. O Google Kubernetes Engine (GKE) monitora os clusters e usa o
serviço do recomendador para fornecer orientações sobre como otimizar o uso da
plataforma.
Para garantir que o cluster permaneça estável e
com bom desempenho, consulte as recomendações do GKE para CRDs que operam, mas
têm um pacote de CA inválido. Use esta orientação para verificar e atualizar CRDs potencialmente mal configurados, se necessário. Para saber mais sobre como gerenciar insights e recomendações dos Recommenders, consulte Otimizar o uso do GKE com insights e recomendações.
Identificar clusters afetados
Para receber insights que identificam clusters afetados por CRDs com pacotes de CA inválidos, siga as instruções para ver insights e recomendações do subtipo K8S_CRD_WITH_INVALID_CA_BUNDLE. É possível conseguir insights das seguintes maneiras:
Use o console Google Cloud .
Use a Google Cloud CLI ou a API Recommender filtrando com o subtipo
K8S_CRD_WITH_INVALID_CA_BUNDLE.
O GKE gera um insight e uma recomendação com o subtipo
K8S_CRD_WITH_INVALID_CA_BUNDLE se o cluster do GKE tiver
um ou mais CRDs informando um caBundle mal configurado para a configuração do cliente
de webhook em spec.conversion.webhook.clientConfig.
As seções a seguir têm instruções para você solucionar problemas de CRDs que
o GKE detectou como possivelmente configurados incorretamente.
Depois que você implementar as instruções e os CRDs forem configurados corretamente, a
recomendação será resolvida em até 24 horas e não vai mais aparecer no console.
Caso tenha se passado menos de 24 horas desde que você implementou a orientação da recomendação, marque-a como resolvida.
Se você não quiser implementar a recomendação, dispense-a.
Identificar CRDs afetados em um cluster
Acesse insights e recomendações para o subtipo K8S_CRD_WITH_INVALID_CA_BUNDLE,
escolhendo um insight de cada vez para resolver problemas. O GKE gera um insight por cluster com um CRD corrompido.
Execute o comando a seguir para descrever o serviço e encontrar CRDs com
pacotes de CA potencialmente problemáticos:
CaBundle: o pacote de CA associado ao webhook de conversão do CRD, se presente. Analise a saída. Se a coluna "caBundle" estiver vazia para um CRD que você sabe que usa um webhook de conversão, isso indica um possível problema com o caBundle.
Recrie a CRD
Para resolver esse erro, recrie o CRD afetado com um pacote de CA válido:
Faça backup dos recursos personalizados associados a essa CRD problemática, se houver. Execute o comando a seguir para exportar os recursos atuais:
kubectlget<crd-name>-oyaml > backup.yaml
Exclua a CRD:
kubectldeletecrd<crd-name>
Verifique se o campo caBundle da CRD contém um certificado PEM bem formado e codificado em base64. Para isso, edite o CRD diretamente ou entre em contato com os autores.
Modifique a definição YAML da CRD, atualizando o campo spec.conversion.webhook.clientConfig.caBundle com os dados válidos do pacote de CA. O resultado será similar a este:
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-09-01 UTC."],[],[],null,["# Troubleshoot CRDs with an invalid CA bundle\n\n[Autopilot](/kubernetes-engine/docs/concepts/autopilot-overview) [Standard](/kubernetes-engine/docs/concepts/choose-cluster-mode)\n\n*** ** * ** ***\n\n[Custom Resource\nDefinitions](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)\n(CRDs) are powerful tools for [extending Kubernetes\ncapabilities](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/).\nHowever, if a CRD contains an invalid or malformed Certificate Authority (CA)\nbundle within its conversion webhook configuration\n`spec.conversion.webhook.clientConfig.caBundle`, it can disrupt cluster\noperations. This can manifest as errors during resource creation, updates, or\ndeletions. Google Kubernetes Engine (GKE) monitors your clusters and uses the\nRecommender service to deliver guidance for how you can optimize your usage of\nthe platform.\n\nTo help you ensure that your cluster remains stable and\nperformant, see recommendations from GKE for CRDs that operate but\nhave an invalid CA bundle. Use this guidance to check your potentially misconfigured CRDs and update them, if necessary. To learn more about how to manage insights and recommendations from\nRecommenders, see [Optimize your usage of GKE with insights and\nrecommendations](/kubernetes-engine/docs/how-to/optimize-with-recommenders).\n\nIdentify impacted clusters\n--------------------------\n\nTo get insights identifying clusters that are affected by CRDs with invalid CA bundles, follow\nthe instructions to [view insights and recommendations](/kubernetes-engine/docs/how-to/optimize-with-recommenders#view-insights-recs) for subtype `K8S_CRD_WITH_INVALID_CA_BUNDLE`. You can get insights in\nthe following ways:\n\n- Use the Google Cloud console.\n- Use the Google Cloud CLI, or the Recommender API, filtering with the subtype `K8S_CRD_WITH_INVALID_CA_BUNDLE`.\n\nAfter you identify the CRDs using the insights, follow the instructions to\n[troubleshoot the misconfigured CA bundle](#troubleshoot-crds).\n\nWhen GKE detects misconfigured CRDs\n-----------------------------------\n\nGKE generates an insight and recommendation with the\n`K8S_CRD_WITH_INVALID_CA_BUNDLE` subtype if the GKE cluster has\none or more CRDs reporting a misconfigured `caBundle` for the webhook client\nconfiguration in `spec.conversion.webhook.clientConfig`.\n\nFollow the instructions to [check CRDs with misconfigured CA bundle](#check-invalid-caBundle).\n\nTroubleshoot the detected CRDs\n------------------------------\n\nThe following sections have instructions for you to troubleshoot the CRDs that\nGKE detected as potentially misconfigured.\n\nAfter you implement the instructions and the CRDs are correctly configured, the\nrecommendation is resolved within 24 hours and no longer appears in the console.\nIf it has been less than 24 hours since you've implemented the guidance of the\nrecommendation, you can [mark the recommendation as\nresolved](/kubernetes-engine/docs/how-to/optimize-with-recommenders#resolve-recommendation).\nIf you don't want to implement the recommendation, you can [dismiss\nit](/kubernetes-engine/docs/how-to/optimize-with-recommenders#dismiss-recommendation).\n\n### Identify affected CRDs in a cluster\n\n1. [View insights and\n recommendations](/kubernetes-engine/docs/how-to/optimize-with-recommenders#view-insights-recs) for subtype `K8S_CRD_WITH_INVALID_CA_BUNDLE`,\n choosing one insight at a time to troubleshoot. GKE generates\n one insight per cluster which has a broken CRD.\n\n2. Run the following command to describe the Service to find CRDs with\n potentially problematic CA bundles:\n\n kubectl get crd -o custom-columns=NAME:.metadata.name,CABUNDLE:.spec.conversion.webhook.clientConfig.caBundle\n\n The output includes the following:\n - **Name**: The name of the CRD.\n - **CaBundle**: The CA bundle associated with the CRD's conversion webhook, if present. Examine the output. If the caBundle column is empty for a CRD that you know utilizes a conversion webhook, this signals a potential issue with the caBundle.\n\n### Recreate the CRD\n\nTo resolve this error, recreate the affected CRD with a valid CA bundle:\n\n1. Back up existing custom resources associated with this problematic\n CRD, if you have any. Run the following command to export the existing\n resources:\n\n kubectl get \u003ccrd-name\u003e -o yaml \u003e backup.yaml\n\n2. Delete the existing CRD:\n\n kubectl delete crd \u003ccrd-name\u003e\n\n3. Ensure that the `caBundle` field of the CRD contains a well-formed,\n base-64-encoded PEM certificate. You can do this either by editing the\n CRD directly or by reaching out to its authors.\n\n4. Modify the CRD YAML definition, updating the\n `spec.conversion.webhook.clientConfig.caBundle` field with the valid\n CA bundle data. The result should look something like the following:\n\n spec:\n conversion:\n webhook:\n clientConfig:\n caBundle: \u003cbase64-encoded-ca-bundle\u003e\n\n5. Apply the corrected CRD:\n\n kubectl apply -f \u003ccorrected-crd-file.yaml\u003e\n\n6. Restore your custom resources:\n\n kubectl apply -f backup.yaml\n\nWhat's next\n-----------\n\n- [Optimize your usage of GKE with insights and\n recommendations](/kubernetes-engine/docs/how-to/optimize-with-recommenders)\n- [Troubleshooting common issues](/kubernetes-engine/docs/troubleshooting)"]]
