Rota el certificado de la AC raíz

En esta página, se explica el certificado de autoridad de certificación raíz de Apigee Hybrid que firma los certificados internos que usan los componentes híbridos para comunicarse entre sí y se describe cómo rotarlo antes de que venza. A partir de Apigee Hybrid v1.17, puedes rotar esta CA raíz por tu cuenta.

Acerca del certificado de la AC raíz

Cada instalación de Apigee Hybrid tiene una sola CA raíz, que se almacena como un Certificate de cert-manager llamado apigee-ca en el espacio de nombres cert-manager. Es una AC autofirmada (isCA: true, nombre común apigee-hybrid) que actúa como raíz de confianza para los certificados internos que emite Hybrid, tanto la TLS mutua (mTLS) entre componentes como la TLS unidireccional (del servidor) que protege los webhook de admisión y la conversión de recursos personalizados. Si esta CA vence, se interrumpirá la comunicación interna entre los componentes híbridos.

Por qué se rota el certificado de la AC raíz

La CA raíz que genera el gráfico híbrido tiene un período de validez de 10 años. Se debe rotar antes de que venza para que los certificados internos que firma se puedan seguir renovando y la comunicación entre componentes nunca se interrumpa. La rotación está diseñada para no tener tiempo de inactividad: durante la transición, tus componentes confían tanto en la CA raíz anterior como en la nueva, por lo que los certificados firmados por cualquiera de ellas siguen siendo válidos hasta que se quita la CA anterior.

Cómo funciona la rotación

Para rotar la CA raíz, debes avanzar tu clúster por cuatro fases, en orden. Solo pasarás a la siguiente fase después de que se complete la fase actual en cada componente. Cada fase se basa en un solo campo de anulaciones, certRotation.phase, aplicado con un helm upgrade del gráfico del operador de Apigee (apigee-operator).

Fase (certRotation.phase) Qué ocurre Es posible revertir la versión
1. CREATE_NEW_CA Se crea una nueva AC raíz (apigee-ca-2) y se agrega al almacén de certificados de confianza de cada componente híbrido. Los componentes aún tienen certificados firmados por la CA anterior, por lo que aún no se cambió nada. Sí
2. CREATE_NEW_LEAF Se emiten nuevos certificados de entidad final firmados por la nueva CA raíz. Tanto la CA raíz anterior como la nueva son de confianza, por lo que el tráfico continúa sin interrupciones. Sí
3. HIDE_OLD_CA Se quita la CA raíz anterior de la configuración de confianza activa. Solo la nueva CA raíz permanece en uso. La reversión aún está disponible en esta fase. Sí
4. CLEANUP Se quitan la CA raíz anterior y sus emisores, y la nueva CA raíz se promociona como la CA raíz del clúster. Esta fase es irreversible. No.

Antes de comenzar

  • Instala las herramientas de línea de comandos de kubectl y helm, y asegúrate de que tu contexto de kubectl apunte al clúster que estás rotando.
  • Asegúrate de que el clúster esté en buen estado. Cada helm upgrade valida que cada ApigeeDeployment esté en el estado running y que la fase que solicitas sea la actual, la siguiente o la de reversión. Si el clúster no está en buen estado o intentas omitir una fase, se rechazará la actualización.
  • Si ejecutas una implementación multirregional, lee esa sección antes de comenzar, ya que todas las regiones deben converger en la misma CA raíz nueva.

Rota la CA raíz

Realiza los siguientes pasos para cada fase que se indica en Cómo funciona la rotación, en orden: aplica la fase y, luego, confirma que se completó antes de pasar a la siguiente. En una implementación multirregional, realiza estos pasos en cada región.

Paso 1: Establece la fase y aplícala

Agrega o actualiza la estrofa certRotation en tu archivo de anulaciones y establece phase en la fase que estás aplicando. Por ejemplo, para iniciar la rotación, haz lo siguiente:

certRotation:
  phase: CREATE_NEW_CA

Prueba el cambio con una ejecución de prueba primero:

helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f OVERRIDES_FILE.yaml \
  --dry-run=server

Luego, aplica el cambio:

helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f OVERRIDES_FILE.yaml

Paso 2: Confirma que se completó la fase

El clúster registra el progreso de la rotación en el ConfigMap cert-info en el espacio de nombres híbrido. Lee su valor de currentPhase: 

kubectl get configmap cert-info -n APIGEE_NAMESPACE \
  -o jsonpath='{.data.currentPhase}'

Una fase solo se completa cuando currentPhase es igual a la fase que acabas de aplicar. currentPhase avanza solo después de que cada componente se haya conciliado con la fase solicitada, por lo que no debes continuar hasta que coincida.

Cuando currentPhase coincide, lee la siguiente fase para aplicar desde el mismo ConfigMap: 

kubectl get configmap cert-info -n APIGEE_NAMESPACE \
  -o jsonpath='{.data.readyForNextPhase}'

Establece certRotation.phase en ese valor y repite los pasos 1 y 2. Continúa hasta que completes la fase CLEANUP.

Implementaciones multirregionales

En una implementación multirregional, cada clúster tiene su propio ConfigMap cert-info, su propio operador y sus propios almacenes de confianza, y todas las regiones deben terminar confiando en la misma CA raíz nueva. El gráfico genera una nueva CA raíz solo cuando el secreto apigee-ca-2 aún no existe, por lo que creas la nueva CA una vez en una región principal y la copias en las otras regiones antes de rotarlas.

Realiza la rotación en el siguiente orden. Confirma currentPhase en una región (consulta el paso 2: Confirma que se completó la fase) antes de pasar esa región a la siguiente fase.

  1. Ejecuta CREATE_NEW_CA en tu región principal. El gráfico genera la nueva CA raíz y la almacena en el secreto apigee-ca-2.
  2. Copia el Secret apigee-ca-2 del espacio de nombres cert-manager de la región principal en el espacio de nombres cert-manager de todas las demás regiones antes de ejecutar CREATE_NEW_CA en esas regiones. Este es el mismo patrón de copia secreta que usas cuando te expandes a una región nueva. Consulta Implementaciones multirregionales.
  3. Ejecuta CREATE_NEW_CA en cada una de las otras regiones, una región a la vez. Como el secreto de apigee-ca-2 ya está presente, el gráfico omite la emisión de una nueva CA y vincula la región a la compartida.
  4. Ejecuta CREATE_NEW_LEAF en cada región.
  5. Ejecuta HIDE_OLD_CA en cada región.
  6. Ejecuta CLEANUP en cada región.
  7. Quita la estrofa certRotation del archivo de anulaciones de cada región para ordenar tu configuración.

A través de CREATE_NEW_CA, CREATE_NEW_LEAF y HIDE_OLD_CA, cada región confía en la AC raíz anterior y la nueva, por lo que las regiones pueden estar en diferentes fases durante este período sin interrumpir el tráfico entre ellas.

Usa tu propia CA

Si deseas usar tu propia CA raíz en lugar de una generada por el gráfico, crea previamente el nuevo secreto de la CA antes de iniciar la rotación. Dado que el gráfico genera una CA solo cuando el secreto de destino está ausente, se usa un secreto existente tal como está.

Los nombres de las CA raíz no son de formato libre. Hybrid espera cada generación de la CA con un nombre fijo: apigee-ca, luego apigee-ca-2, apigee-ca-3, etcétera. El gráfico busca la siguiente CA con exactamente ese nombre. Cuando traes tu propia CA, debes crear el secreto con el siguiente nombre exacto (apigee-ca-2 para la primera rotación); el gráfico no detecta una CA creada con ningún otro nombre. Para encontrar el nombre secreto actual y el siguiente nombre que se usará, enumera los certificados de CA y los secretos que los respaldan: 

kubectl get certificate -n cert-manager \
  -o custom-columns=CERTIFICATE:.metadata.name,SECRET:.spec.secretName

Consulta Realiza un seguimiento del vencimiento de la CA raíz para obtener más formas de inspeccionar la generación en la que se encuentra tu clúster.

  1. Antes de ejecutar CREATE_NEW_CA, crea un Secret con el siguiente nombre de la CA (apigee-ca-2 para la primera rotación) en el espacio de nombres cert-manager, que contenga tu certificado de la AC y tu clave privada. El secreto debe ser del tipo kubernetes.io/tls y contener tres claves: tls.crt, tls.key y ca.crt. Como kubectl create secret tls no puede establecer la clave ca.crt, usa la forma genérica: 
    kubectl create secret generic apigee-ca-2 \
  --namespace cert-manager \
  --type=kubernetes.io/tls \
  --from-file=tls.crt=CERT_FILE \
  --from-file=tls.key=KEY_FILE \
  --from-file=ca.crt=CA_FILE
  2. Ejecuta la rotación como se describe en Rota la AC raíz. Durante CREATE_NEW_CA, el gráfico detecta tu secreto de apigee-ca-2, omite la generación de una CA y vincula el nuevo emisor (apigee-ca-issuer-2) a tu CA. Todas las demás fases permanecen sin cambios.

Cuando traes tu propia CA, su vida útil es la que lleva tu certificado, no los 10 años predeterminados del gráfico.

Cómo revertir una rotación

Todas las fases anteriores a CLEANUP se pueden revertir. Para revertir la actualización, establece certRotation.phase en el valor que el clúster informa como el objetivo de reversión y aplícalo con helm upgrade, exactamente como aplicas una fase de avance.

Lee el destino de reversión del ConfigMap cert-info:

kubectl get configmap cert-info -n APIGEE_NAMESPACE \
  -o jsonpath='{.data.readyForRollbackPhase}'

Los objetivos de avance y reversión para cada fase son los siguientes:

Fase actual Próxima fase Fase de reversión
PHASE_UNSPECIFIED (no iniciado) CREATE_NEW_CA PHASE_UNSPECIFIED
CREATE_NEW_CA CREATE_NEW_LEAF PHASE_UNSPECIFIED
CREATE_NEW_LEAF HIDE_OLD_CA CREATE_NEW_CA
HIDE_OLD_CA CLEANUP CREATE_NEW_LEAF
CLEANUP — (rotación completada) — (ninguno; irreversible)

Seguimiento del vencimiento de la CA raíz

Debido a que la rotación de Apigee hybrid se basa en el cliente, eres responsable de rotar la CA raíz antes de que venza. Haz un seguimiento del vencimiento del certificado apigee-ca y planifica la rotación antes de esa fecha para tener tiempo de completar las cuatro fases en cada región.

Para verificar cuándo vence la CA raíz, enumera los certificados de CA en el espacio de nombres cert-manager y, luego, lee la fecha de vencimiento de la generación que usas actualmente: 

kubectl get certificate -n cert-manager

kubectl get certificate apigee-ca -n cert-manager \
  -o jsonpath='{.status.notAfter}'

El primer comando enumera cada generación de la CA raíz (apigee-ca, apigee-ca-2, etcétera). El segundo imprime la fecha de vencimiento del certificado con nombre; ejecútalo en la generación que se usa actualmente.

Apigee Hybrid Automated issue surfacing informa los problemas del clúster que detecta como recursos ApigeeIssue, que puedes enumerar con kubectl get apigeeissues. Verifica si hay problemas en la superficie como parte de tu supervisión habitual.

¿Qué sigue?