Descripción general de la herencia del espacio de nombres

En esta página, se describe cómo el Sincronizador de configuración aplica los archivos de configuración a los espacios de nombres de tus clústeres en una jerarquía, según la estructura del repositorio. También puedes obtener información para configurar espacios de nombres y objetos con permisos del espacios de nombres.

Cómo funciona la herencia del espacio de nombres

Uno de los aspectos más importantes del Sincronizador de configuración es la capacidad de aplicar archivos de configuración a grupos de espacios de nombres de forma automática en todos los clústeres en los que esos espacios de nombres existen (o deberían existir), en función de dónde se encuentren los archivos de configuración en el repositorio.

El Sincronizador de configuración ingresa una noción de herencia en el directorio namespaces/ del repositorio y en todos sus subdirectorios. Los archivos de configuración en otros directorios del repositorio, como cluster/, no están sujetas a la herencia.

En el repositorio, el directorio namespaces/ puede contener dos tipos diferentes de subdirectorios:

  • Un directorio de espacio de nombres contiene un archivo de configuración para un espacio de nombres. El nombre del archivo que contiene la configuración no es importante, pero la configuración debe tener kind: Namespace. Un directorio de espacio de nombres también puede contener archivos de configuración para otros tipos de objetos de Kubernetes. Sin embargo, no puede contener subdirectorios. Un archivo de configuración de espacio de nombres representa un espacio de nombres real en un clúster.

  • Un directorio de espacio de nombres abstracto contiene directorios de espacio de nombres. También puede contener archivos de configuración para otros objetos de Kubernetes, pero no puede contener un archivo de configuración para un espacio de nombres directamente. Un directorio de espacio de nombres abstracto no representa un objeto en un clúster de Kubernetes, pero sí lo hacen sus directorios de espacio de nombres descendientes.

Si te olvidas de agregar un archivo de configuración para un espacio de nombres a un directorio de espacio de nombres, si agregas un directorio a un subdirectorio de espacio de nombres o si agregas un archivo de configuración para un espacio de nombres a un directorio de espacio de nombres abstracto, el resultado es un error KNV1003: IllegalNamespaceSubdirectoryError.

Los archivos de configuración en un directorio de espacio de nombres se aplican solo a ese espacio de nombres, mientras que los que están en un directorio de espacio de nombres abstracto se aplican a todos los directorios de espacio de nombres descendientes de ese espacio de nombres abstracto (o a los espacios de nombres descendientes que coincidan con el configuración NamespaceSelector de un archivo de configuración, si es que lo hay).

Como la herencia de un archivo de configuración en el directorio namespaces/ se basa sobre todo en su ubicación dentro del árbol de directorios del repositorio, puedes explorar el repositorio para descubrir qué archivos de configuración se aplican a un espacio de nombres en particular en un clúster determinado.

En el siguiente diagrama, se muestra cómo se heredan los archivos de configuración dentro del directorio namespaces/ del repositorio de ejemplo. Los rectángulos azules representan directorios de espacio de nombres abstractos y los rectángulos naranjas representan espacios de nombres reales en Kubernetes.

Diagrama que muestra la herencia de archivos de configuración en el repositorio de ejemplo

Por ejemplo, abre el archivo viewers-rolebinding.yaml en tu navegador. Le otorga a cualquier miembro del grupo system:serviceaccounts:audit la función ClusterRole view en cada espacio de nombres administrado por el Sincronizador de configuración de cada clúster inscrito, porque existe en el directorio namespaces.

Ahora abre el directorio namespaces/online/ en tu navegador. El directorio online es un directorio de espacio de nombres abstracto, porque no tiene un archivo de configuración para un espacio de nombres. Haz clic en el directorio shipping-app-backend. También es un directorio de espacio de nombres abstracto y contiene dos archivos de configuración (pod-creator-rolebinding.yaml y quota.yaml). Cada uno de sus tres subdirectorios es un directorio de espacio de nombres, porque contiene un archivo de configuración para un espacio de nombres. El nombre del archivo no es significativo, pero este repositorio usa ese nombre de archivo para todos los archivos de configuración del espacio de nombres por convención. Cada uno de esos espacios de nombres hereda los archivos de configuración pod-creator-rolebinding.yaml y quota.yaml en el directorio de espacio de nombres abstracto shipping-app-backend.

El directorio de espacio de nombres shipping-dev tiene un archivo de configuración adicional para el RoleBinding job-creators, pero los otros dos directorios de espacio de nombres no lo tienen, por lo que no tienen ese RoleBinding (a menos que alguien lo cree de forma manual).

Nombres no permitidos en namespaces/

Los siguientes elementos están reservados y no se pueden usar como espacios de nombres ni como directorios de espacio de nombres abstractos dentro del directorio namespaces/ del repositorio:

  • config-management-system

Archivos de configuración de ejemplo

Archivos de configuración del espacio de nombres

Este archivo de configuración crea un espacio de nombres llamado audit.

apiVersion: v1
kind: Namespace
metadata:
  name: audit

Cuando creas un archivo de configuración de espacio de nombres, también puedes agregar una etiqueta al espacio de nombres. Esto puede ser útil junto con NamespaceSelector.

El siguiente archivo de configuración crea un espacio de nombres llamado shipping-prod si todavía no existe, o si ya existe pero no tiene la etiqueta configmanagement.gke.io/managed, y le asigna env: prod. También garantiza que una anotación llamada audit esté configurada en true para el espacio de nombres. Si alguien modifica o quita esa anotación de forma manual, el Sincronizador de configuración restablece su valor en función del valor del archivo de configuración con rapidez.

apiVersion: v1
kind: Namespace
metadata:
  name: shipping-prod
  labels:
    env: prod
  annotations:
    audit: "true"

Archivo de configuración de ResourceQuota

Este ejemplo crea un objeto ResourceQuota llamado quota, que establece un límite estricto de 1 pod, 0.1 CPU (100 mili-CPU) y 100 MiB de memoria.

kind: ResourceQuota
apiVersion: v1
metadata:
  name: quota
spec:
  hard:
    pods: "1"
    cpu: "100m"
    memory: 100Mi

Si ubicas este archivo de configuración en un directorio que se aplica a un espacio de nombres específico (namespaces/[NAMESPACE_NAME]), el archivo se aplica solo a ese espacio de nombres. Si ubicas este archivo de configuración en un directorio de espacio de nombres abstracto (namespaces/) que contiene descendientes del espacios de nombres, se aplica un objeto ResourceQuota independiente para cada descendiente del espacio de nombres.

Excluye espacios de nombres de la herencia

Los selectores de espacios de nombres se pueden usar para eximir a determinados espacios de nombres de heredar un recurso en el árbol.

En el siguiente ejemplo, se permite que todos los espacios de nombres, excepto los etiquetados como quota-exempt: exempt, hereden el objeto ResourceQuota anotado de forma adecuada en el directorio raíz /namespaces:

kind: NamespaceSelector
 apiVersion: configmanagement.gke.io/v1
 metadata:
   name: excludes-exempt-namespaces
 spec:
   selector:
     matchExpressions:
       - key: quota-exempt
         operator: NotIn
          values:
            - exempt

Para obtener más información sobre NamesspaceSelectors en el Sincronizador de configuración, consulta Limita los espacios de nombres a los que afecta un archivo de configuración.

Efectos de las operaciones de Git en espacios de nombres

Las operaciones de Git que crean o borran directorios de espacio de nombres dentro del directorio namespaces/ pueden causar efectos diferentes a los previstos en un principio. En esta sección, se abarcan esas interacciones.

Crea un directorio en namespaces/

Cuando se confirma una jerarquía namespaces/ válida para el repositorio, el Sincronizador de configuración crea espacios de nombres y, luego, crea objetos de Kubernetes en esos espacios para cada archivo de configuración que contiene o hereda el directorio de espacio de nombres.

Borra un directorio de namespaces/

La eliminación de un directorio de espacio de nombres es una operación destructiva. El espacio de nombres se borra, junto con todo su contenido, en cada clúster administrado por el Sincronizador de configuración en el que existe el espacio de nombres.

Si borras un directorio de espacio de nombres abstracto que contiene directorios de espacio de nombres descendientes, todos esos espacios de nombres y sus contenidos se borran de todos los clústeres que administra el Sincronizador de configuración.

Cambia el nombre de un directorio en namespaces/

Cuando cambias el nombre de un directorio de espacio de nombres, se realiza una eliminación seguida de una creación, por lo que también es una operación destructiva.

El cambio de nombre de un directorio de espacio de nombres abstracto no tiene efecto visible de forma externa.

Mueve un directorio en namespaces/

Si mueves un espacio de nombres o un directorio de espacio de nombres abstracto dentro de namespaces/, no se borra el espacio de nombres ni los objetos en él, excepto cuando el espacio de nombres comienza a heredar un archivo de configuración de un directorio de espacio de nombres abstracto o deja de hacerlo debido a un cambio en su jerarquía.

Integración con el controlador de jerarquía

El controlador de jerarquía tiene un concepto muy similar de la herencia de espacios de nombres compatible con los espacios de nombres abstractos, como se describe en la documentación del controlador de jerarquía.

Selecciona espacios de nombres relacionados

Hay momentos en los que quizás desees aplicar políticas a conjuntos de espacios de nombres relacionados a través de un principal en común. El controlador de jerarquía admite esto mediante un concepto conocido como etiquetas de árbol, que también son compatibles con los espacios de nombres abstractos, incluso si el controlador de jerarquía no está habilitado.

Las etiquetas de árbol son etiquetas de Kubernetes que tienen el siguiente formato:

<namespace-name>.tree.hnc.x-k8s.io/depth: <depth>

Estas etiquetas te permiten escribir selectores de espacios de nombres que, por ejemplo, se pueden usar como parte de una política de red que permite el tráfico dentro de un subárbol de espacios de nombres relacionado, pero inhabilita el tráfico fuera de ese subárbol.

Para ilustrar este concepto, regresemos al diagrama del repositorio de ejemplo.

Diagrama que muestra la herencia de archivos de configuración en el repositorio de ejemplo

Por ejemplo, el espacio de nombres shipping-prod tiene las siguientes etiquetas de árbol:

shipping-prod.tree.hnc.x-k8s.io/depth: 0
shipping-app-backend.tree.hnc.x-k8s.io/depth: 1
online.tree.hnc.x-k8s.io/depth: 2
root.tree.hnc.x-k8s.io/depth: 3

Puedes usar kubectl para inspeccionar estas relaciones directamente en el clúster, sin tener acceso al repositorio de Git:

# View all descendants of 'root'
kubectl get namespaces -l 'root.tree.hnc.x-k8s.io/depth'

# View any immediate children of 'shipping-app-backend'
kubectl get namespaces -l 'shipping-app-backend.tree.hnc.x-k8s.io/depth=1'

El controlador de jerarquía también propaga cualquier etiqueta de árbol de los espacios de nombres abstractos a cualquier espacio de nombres descendiente. Por ejemplo, si creas un espacio de nombres secundario de shipping-prod de la siguiente manera:

kubectl hns create shipping-prod-v1 -n shipping-prod

En este caso, el espacio de nombres shipping-prod-v1 incluiría todas las etiquetas de su superior, además de las propias, con la profundidad ajustada de forma adecuada:

shipping-prod-v1.tree.hnc.x-k8s.io/depth: 0
shipping-prod.tree.hnc.x-k8s.io/depth: 1
shipping-app-backend.tree.hnc.x-k8s.io/depth: 2
online.tree.hnc.x-k8s.io/depth: 3
root.tree.hnc.x-k8s.io/depth: 4

¿Qué sigue?