kubernetes-sigs/aws-iam-authenticatorUna herramienta para utilizar credenciales de AWS IAM para autenticarse en un clúster de Kubernetes.
Una herramienta para usar credenciales de AWS IAM para autenticarse en un clúster de Kubernetes. El trabajo inicial de esta herramienta fue impulsado por Heptio. El proyecto recibe contribuciones de múltiples ingenieros de la comunidad y actualmente es mantenido por Heptio y los ingenieros de Amazon EKS OSS.
Si eres un administrador que ejecuta un clúster de Kubernetes en AWS, ya necesitas gestionar las credenciales de AWS IAM para aprovisionar y actualizar el clúster. Al usar AWS IAM Authenticator for Kubernetes, evitas tener que gestionar una credencial separada para el acceso a Kubernetes. AWS IAM también proporciona una serie de buenas propiedades, como una pista de auditoría fuera de banda (a través de CloudTrail) y la aplicación de 2FA/MFA.
Si estás construyendo un instalador de Kubernetes en AWS, AWS IAM Authenticator for Kubernetes puede simplificar tu proceso de arranque.
No necesitarás sacar de algún modo tu credencial de administrador inicial de forma segura de tu clúster recién instalado.
En su lugar, puedes crear un rol dedicado KubernetesAdmin en el momento de aprovisionar el clúster y configurar Authenticator para permitir los inicios de sesión de administradores del clúster.
Suponiendo que tienes un clúster ejecutándose en AWS y quieres añadir soporte de AWS IAM Authenticator for Kubernetes, necesitas:
Primero, debes crear uno o más roles de IAM que se asignarán a usuarios/grupos dentro de tu clúster de Kubernetes. La forma más fácil de hacerlo es iniciar sesión en la consola de AWS:
Esto creará un rol de IAM sin permisos que puede ser asumido por usuarios/roles autorizados en tu cuenta. Anota el Nombre de Recurso de Amazon (ARN) de tu rol, que necesitarás más abajo.
También puedes hacer esto en un solo paso usando la AWS CLI en lugar de la consola de AWS:```sh
ACCOUNT_ID=$(aws sts get-caller-identity --output text --query 'Account')
POLICY=$(echo -n '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"AWS":"arn:aws:iam::'; echo -n "$ACCOUNT_ID"; echo -n ':root"},"Action":"sts:AssumeRole","Condition":{}}]}')
aws iam create-role
--role-name KubernetesAdmin
--description "Kubernetes administrator role (for AWS IAM Authenticator for Kubernetes)."
--assume-role-policy-document "$POLICY"
--output text
--query 'Role.Arn'
Puedes omitir este paso y usar:
- Un rol existente (como un rol de acceso entre cuentas).
- Un usuario de IAM (consulta `mapUsers` a continuación).
- Una instancia de EC2 o un rol federado (consulta `mapRoles` a continuación).
### 2. Ejecutar el servidor
El servidor está diseñado para ejecutarse en cada uno de tus nodos maestros como un DaemonSet con red de host, de modo que pueda exponer un puerto localhost.
Para una configuración de ejemplo de ConfigMap y DaemonSet, consulta [`deploy/example.yaml`](https://github.com/kubernetes-sigs/aws-iam-authenticator/blob/HEAD/deploy/example.yaml).
Antes de aplicarla, actualiza estos valores para tu clúster:
- Reemplaza los ARN de IAM de marcador de posición (`arn:aws:iam::000000000000:...`) en `config.yaml`.
- Establece `clusterID` a un valor único para tu clúster.
- Verifica que las reglas de programación del DaemonSet coincidan con las etiquetas/taints de tus nodos del plano de control.
Luego despliégala:```sh
kubectl apply -f deploy/example.yaml
kubectl -n kube-system rollout status daemonset/aws-iam-authenticator
kubectl -n kube-system get pods -l k8s-app=aws-iam-authenticator
Una vez que el pod se esté ejecutando en un nodo del plano de control, aws-iam-authenticator server creará el kubeconfig del webhook en el host en /etc/kubernetes/aws-iam-authenticator/kubeconfig.yaml (o la ruta configurada mediante --generate-kubeconfig).
Si estás creando un instalador automatizado, también puedes pre-generar fácilmente el certificado, la clave y los archivos kubeconfig del webhook usando aws-iam-authenticator init.
Este comando generará los archivos y los colocará en los directorios de salida configurados.
Puedes ejecutar esto en cada nodo maestro antes de iniciar el servidor de la API. También puedes generarlos antes de aprovisionar los nodos maestros e instalarlos en las rutas de host correspondientes.
Si no pre-generas los archivos, aws-iam-authenticator server los generará bajo demanda.
Esto funciona, pero requiere que reinicies tu servidor de la API de Kubernetes después de la instalación.
La API de Kubernetes se integra con AWS IAM Authenticator for Kubernetes mediante un webhook de autenticación por token.
Cuando ejecutes aws-iam-authenticator server, generará un archivo de configuración de webhook y lo guardará en el sistema de archivos del host.
Deberás agregar un solo flag adicional a la configuración de tu servidor de la API:```
--authentication-token-webhook-config-file=/etc/kubernetes/aws-iam-authenticator/kubeconfig.yaml
En muchos clústeres, el servidor de API se ejecuta como un pod estático.
Puedes añadir la bandera a `/etc/kubernetes/manifests/kube-apiserver.yaml`.
Asegúrate de que el directorio del host `/etc/kubernetes/aws-iam-authenticator/` esté montado en tu pod del servidor de API.
También puede que necesites reiniciar el daemon de kubelet en tu nodo maestro para que recoja la definición actualizada del pod estático:```
systemctl restart kubelet.service
El comportamiento predeterminado del servidor es obtener las asignaciones exclusivamente de los
campos mapUsers y mapRoles de su archivo de configuración. Consulta Formato de
Configuración Completo a continuación para más detalles.
Con la opción --backend-mode, puedes configurar el servidor para obtener las
asignaciones de dos backends adicionales: un ConfigMap de estilo EKS
(--backend-mode=EKSConfigMap) o recursos personalizados IAMIdentityMapping
(--backend-mode=CRD). El backend predeterminado, el archivo de configuración del servidor
que está montado por el pod del servidor, corresponde a --backend-mode=MountedFile.
Puedes pasar una lista separada por comas de estos backends para que el servidor los busque
en orden. Por ejemplo, con --backend-mode=EKSConfigMap,MountedFile, el
servidor buscará asignaciones en el ConfigMap de estilo EKS y, si no
encuentra una asignación para el rol/usuario de IAM dado, buscará en el archivo de configuración del servidor. Si una
asignación para el mismo rol/usuario de IAM existe en varios backends, el servidor
usará la asignación del backend que aparezca primero en la lista separada por comas.
En este ejemplo, si se encuentra una asignación en el ConfigMap de EKS, entonces se
usará sin importar si existe una asignación duplicada o conflictiva en el archivo de configuración del servidor.
Ten en cuenta que al configurar un único backend, el servidor solo obtendrá las asignaciones de
ese backend e ignorará los demás, incluso si existen. Por ejemplo, con
--backend-mode=CRD, el servidor solo obtendrá las asignaciones de IAMIdentityMappings
e ignorará el archivo montado y el ConfigMap de EKS.
MountedFileEste es el backend predeterminado de asignaciones y es suficiente para la mayoría de los usuarios. Consulta Formato de Configuración Completo a continuación para más detalles.
CRD (alfa)Este backend modela cada asignación de IAM como un recurso
personalizado
IAMIdentityMapping de Kubernetes.
Este enfoque te permite mantener las asignaciones de forma nativa de Kubernetes usando
kubectl o la API. Además, los errores de sintaxis (como YAML desalineado) pueden
detectarse más fácilmente y no afectarán a todas las asignaciones.
Para configurar un CRD IAMIdentityMapping, primero tendrás que apply el manifiesto del CRD:```
kubectl apply -f deploy/iamidentitymapping.yaml
Con los CRDs desplegados, puedes entonces crear Custom Resources que modelen tus
Identidades IAM. Consulta
[`./deploy/example-iamidentitymapping.yaml`](https://github.com/kubernetes-sigs/aws-iam-authenticator/blob/HEAD/deploy/example-iamidentitymapping.yaml):```
---
apiVersion: iamauthenticator.k8s.aws/v1alpha1
kind: IAMIdentityMapping
metadata:
name: kubernetes-admin
spec:
# Arn of the User or Role to be allowed to authenticate
arn: arn:aws:iam::XXXXXXXXXXXX:user/KubernetesAdmin
# Username that Kubernetes will see the user as, this is useful for setting
# up allowed specific permissions for different users
username: kubernetes-admin
# Groups to be attached to your users/roles. For example `system:masters` to
# create cluster admin, or `system:nodes`, `system:bootstrappers` for nodes to
# access the API server.
groups:
- system:masters
EKSConfigMapEl ConfigMap kube-system/aws-auth de estilo EKS sirve como backend. El
ConfigMap debe tener exactamente el mismo formato que en los clústeres EKS:
https://docs.aws.amazon.com/eks/latest/userguide/add-user-role.html. Esto es
útil si estás migrando desde/hacia EKS y quieres conservar tus mapeos, o estás
ejecutando EKS además de otros clúster(es) de AWS y quieres tener los mismos
mapeos en cada uno.
DynamicFileUn archivo local especificado por cfg.dynamicfilepath puede servir como backend. El contenido del archivo debe tener exactamente el mismo formato que el EKSConfigMap. Cada vez que el contenido de este archivo cambie, authenticator lo recargará automáticamente. Esto proporciona más flexibilidad a la hora de gestionar los mapeos de ARN.
Check https://github.com/kubernetes-sigs/aws-iam-authenticator/blob/master/hack/dev/authenticator_with_dynamicfile_mode.yaml sobre cómo configurar el modo DynamicFile.
Ejecuta make e2e RUNNER=kind para probar con un clúster kind con el modo DynamicFile habilitado.
aws-iam-authenticator puede admitir un prefijo reservado para el nombre de usuario de k8s. Si el prefijo reservado está establecido, entonces el nombre de usuario con el prefijo reservado no será autenticado y se mostrará el error "username must not begin with with the following prefixes:".
Check https://github.com/kubernetes-sigs/aws-iam-authenticator/blob/master/hack/dev/authenticator_with_dynamicfile_mode.yaml sobre cómo configurar el prefijo reservado.
Finalmente, una vez que el servidor esté configurado, querrás autenticarte.
Todavía necesitarás un kubeconfig que tenga los datos públicos sobre tu clúster (certificado CA del clúster, dirección del endpoint).
La sección users de tu configuración, sin embargo, debe incluir una sección exec (consulta la documentación del plugin de credenciales de kubectl):```yaml
users:
Esto significa que el `kubeconfig` es información totalmente pública y puede compartirse entre todos los usuarios de Authenticator.
Puede tener sentido subirlo a una ubicación pública de confianza, como AWS S3.
Asegúrate de tener instalado el binario `aws-iam-authenticator`.
Puedes instalarlo con `go install sigs.k8s.io/aws-iam-authenticator/cmd/aws-iam-authenticator@latest`.
Para autenticarte, ejecuta `kubectl --kubeconfig /path/to/kubeconfig" [...]`.
kubectl hará `exec` del binario `aws-iam-authenticator` con los parámetros suministrados en tu kubeconfig, lo que generará un token y lo pasará al apiserver.
El token es válido durante 15 minutos (el valor más corto que AWS permite) y puede reutilizarse varias veces.
También puedes especificar el nombre de sesión al generar el token incluyendo el parámetro `--session-name or -s`. Este parámetro no puede usarse junto con `--forward-session-name`.
También puedes omitir `-r ROLE_ARN` para firmar el token con tus credenciales existentes sin asumir un rol dedicado.
Esto es útil si quieres autenticarte directamente como un usuario de IAM o si quieres autenticarte utilizando un rol de instancia EC2 o un rol federado.
## Uso de Kops
Los clústeres gestionados por [Kops](https://github.com/kubernetes/kops) pueden configurarse para usar Authenticator. Para instrucciones de uso, consulta la [documentación de Kops](https://kops.sigs.k8s.io/authentication/#aws-iam-authenticator).
## ¿Cómo funciona?
Funciona usando el endpoint de la API [`sts:GetCallerIdentity`](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetCallerIdentity.html) de AWS.
Este endpoint devuelve información sobre las credenciales IAM de AWS que uses para conectarte a él.
#### Lado del cliente (`aws-iam-authenticator token`)
Usamos esta API de una manera algo inusual: hacemos que el cliente de Authenticator genere y prefirme una solicitud para el endpoint.
Serializamos esa solicitud en un token que puede pasar a través del sistema de autenticación de Kubernetes.
#### Lado del servidor (`aws-iam-authenticator server`)
El token se pasa a través del servidor de API de Kubernetes hasta el endpoint `/authenticate` del servidor de Authenticator mediante una configuración de webhook.
El servidor de Authenticator valida todos los parámetros de la solicitud prefirmada para asegurarse de que nada parezca extraño.
Luego envía la solicitud al servidor real `https://sts.amazonaws.com`, que valida la firma HMAC del cliente y devuelve información sobre el usuario.
Ahora que el servidor conoce la identidad AWS del cliente, traduce esta identidad a un usuario y grupos de Kubernetes mediante un simple mapeo estático.
Este mecanismo está tomado, con algunos cambios, de [Vault](https://www.vaultproject.io/docs/auth/aws.html#iam-auth-method).
## ¿Qué es un ID de clúster?
El ID de clúster de Authenticator es un identificador único por clúster que previene ciertos ataques de repetición.
Específicamente, evita que un servidor de Authenticator (p. ej., en un entorno de desarrollo) use el token de un cliente para autenticarse en otro servidor de Authenticator en otro clúster.
El ID de clúster debe ser único por clúster, pero no necesita ser un secreto.
Algunas buenas opciones son:
- Un ID aleatorio, como el de `openssl rand 16 -hex`
- El nombre de dominio de tu servidor de API de Kubernetes
La [documentación de Vault](https://www.vaultproject.io/docs/auth/aws.html#iam-auth-method) también explica este ataque (consulta `X-Vault-AWS-IAM-Server-ID`).
## Especificación de credenciales y uso de perfiles de AWS
Las credenciales pueden especificarse para usarlas con `aws-iam-authenticator` mediante cualquiera de los métodos disponibles en el
[AWS SDK for Go](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials).
Esto incluye especificar credenciales de AWS con variables de entorno o utilizando un archivo de credenciales.
Los [perfiles con nombre](https://docs.aws.amazon.com/cli/latest/userguide/cli-multiple-profiles.html) de AWS son compatibles con `aws-iam-authenticator`
a través de la variable de entorno `AWS_PROFILE`. Por ejemplo, para autenticarte con credenciales especificadas en el perfil _dev_, `AWS_PROFILE` puede
exportarse o especificarse explícitamente (p. ej., `AWS_PROFILE=dev kubectl get all`). Si no se establece `AWS_PROFILE`, se usa el perfil _default_.
`AWS_PROFILE` también puede especificarse directamente en el archivo kubeconfig
[como parte del flujo `exec`](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#configuration). Por ejemplo, para especificar
que las credenciales del perfil con nombre _dev_ deben ser utilizadas siempre por `aws-iam-authenticator`, tu kubeconfig incluiría una clave `env`
que establece el perfil:```yaml
apiVersion: v1
clusters:
- cluster:
server: ${server}
certificate-authority-data: ${cert}
name: kubernetes
contexts:
- context:
cluster: kubernetes
user: aws
name: aws
current-context: aws
kind: Config
preferences: {}
users:
- name: aws
user:
exec:
apiVersion: client.authentication.k8s.io/v1beta1
command: aws-iam-authenticator
env:
- name: "AWS_PROFILE"
value: "dev"
args:
- "token"
- "-i"
- "mycluster"
Este método permite que el perfil adecuado se utilice implícitamente. Ten en cuenta que cualquier variable de entorno establecida como parte del flujo exec tendrá prioridad sobre lo que ya esté configurado en tu entorno.
Los usuarios federados de AWS a menudo tendrán un atributo "significativo" asignado a su rol asumido, como una dirección de correo electrónico, a través de la configuración de AWS de la cuenta.
Estas sesiones asumidas tienen unas pocas partes, el role id
y el caller-specified-role-name. Por defecto, cuando un usuario federado utiliza la opción --role de aws-iam-authenticator para asumir un nuevo rol, el
caller-specified-role-name se convertirá en un token aleatorio y el role id se transmitirá al rol recién asumido.
El uso de aws-iam-authenticator token ... --forward-session-name asignará el atributo original caller-specified-role-name a la nueva sesión asumida de STS.
Esto puede ser útil para intentar asociar rápidamente "quién realizó la acción X en el clúster K8".
Ten en cuenta que esto no debe considerarse definitivo y debe contrastarse mediante el role id (que permanece consistente) con los registros de CloudTrail,
ya que un usuario podría potencialmente cambiar esto en el lado del cliente.
Es posible realizar peticiones a la API de Kubernetes desde un cliente que esté fuera del clúster, ya sea utilizando la
API REST de Kubernetes directamente o desde uno de los clientes de Kubernetes específicos de un lenguaje
(p. ej., Python). Para ello, debes crear un token de portador que
se incluya con la petición a la API. Este token de portador requiere que añadas la cadena k8s-aws-v1. junto con una
cadena codificada en base64 de una solicitud HTTP firmada a la API de consulta STS GetCallerIdentity. Esto se envía entonces en la
cabecera Authorization de la petición. Sin embargo, cabe señalar que el IAM Authenticator omite explícitamente
el relleno (padding) base64 para evitar cualquier carácter =, lo que garantiza una cadena segura para usar en URLs. A continuación se muestra un ejemplo en
Python de cómo se construiría este token:```python
import base64
import boto3
import re
from botocore.signers import RequestSigner
def get_bearer_token(cluster_id, region): STS_TOKEN_EXPIRES_IN = 60 session = boto3.session.Session()
client = session.client('sts', region_name=region)
service_id = client.meta.service_model.service_id
signer = RequestSigner(
service_id,
region,
'sts',
'v4',
session.get_credentials(),
session.events
)
params = {
'method': 'GET',
'url': 'https://sts.{}.amazonaws.com/?Action=GetCallerIdentity&Version=2011-06-15'.format(region),
'body': {},
'headers': {
'x-k8s-aws-id': cluster_id
},
'context': {}
}
signed_url = signer.generate_presigned_url(
params,
region_name=region,
expires_in=STS_TOKEN_EXPIRES_IN,
operation_name=''
)
base64_url = base64.urlsafe_b64encode(signed_url.encode('utf-8')).decode('utf-8')
# remove any base64 encoding padding:
return 'k8s-aws-v1.' + re.sub(r'=*', '', base64_url)
headers = {'Authorization': 'Bearer ' + get_bearer_token('my_cluster', 'us-east-1')}
## Solución de problemas
Si tu cliente falla con un error como `could not get token: AccessDenied [...]`, puedes intentar asumir el rol directamente con la AWS CLI:```sh
# AWS CLI version of `aws-iam-authenticator token -r arn:aws:iam::ACCOUNT:role/ROLE`:
$ aws sts assume-role --role-arn arn:aws:iam::ACCOUNT:role/ROLE --role-session-name test
Si eso falla, hay algunos posibles problemas que verificar:
Asegúrate de que tus credenciales base de AWS estén disponibles en tu shell (aws sts get-caller-identity puede ayudar a solucionar esto).
Asegúrate de que el rol de destino permita el acceso de tu cuenta de origen (en la política de confianza del rol).
Asegúrate de que tu principal de origen (usuario/rol/grupo) tenga una política de IAM que permita sts:AssumeRole para el rol de destino.
Asegúrate de no tener políticas de denegación explícitas adjuntas a tu usuario, grupo o en AWS Organizations que impidan sts:AssumeRole.
Prueba simular la llamada sts:AssumeRole en el Simulador de políticas.
El cliente y el servidor tienen el mismo formato de configuración. Pueden compartir exactamente el mismo archivo de configuración, ya que no hay secretos almacenados en la configuración.```yaml
clusterID: my-dev-cluster.example.com
aws-iam-authenticator tokendefaultRole: arn:aws:iam::000000000000:role/KubernetesAdmin
server:
port: 21362 # (default)
stateDir: /var/aws-iam-authenticator # (default)
path where a generated webhook kubeconfig will be stored.generateKubeconfig: /etc/kubernetes/aws-iam-authenticator.kubeconfig # (default)
ec2DescribeInstancesRoleARN: arn:aws:iam::000000000000:role/DescribeInstancesRole
scrubbedAccounts:
@ characters- characters.mapRoles:
mapUsers:
mapAccounts:
backendMode:
## Desarrollo
Consulte la página de [desarrollo](https://github.com/kubernetes-sigs/aws-iam-authenticator/blob/HEAD/docs/development.md).
## Comunidad, discusión, contribución y soporte
Aprenda cómo participar en la comunidad de Kubernetes en la [página de la comunidad](http://kubernetes.io/community/).
Puede contactar a los mantenedores de este proyecto en:
- [Slack](https://kubernetes.slack.com/messages/sig-aws)
- [Lista de correo](https://groups.google.com/forum/#!forum/kubernetes-sig-aws)
### Código de conducta
La participación en la comunidad de Kubernetes se rige por el [Código de conducta de Kubernetes](https://github.com/kubernetes-sigs/aws-iam-authenticator/blob/HEAD/code-of-conduct.md).