kubernetes-sigs/aws-iam-authenticatorUn outil pour utiliser les identifiants IAM AWS afin de s'authentifier à un cluster Kubernetes.
Un outil pour utiliser les identifiants AWS IAM afin de s'authentifier auprès d'un cluster Kubernetes. Le travail initial sur cet outil a été mené par Heptio. Le projet reçoit des contributions de plusieurs ingénieurs de la communauté et est actuellement maintenu par Heptio et les ingénieurs OSS d'Amazon EKS.
Si vous êtes un administrateur exécutant un cluster Kubernetes sur AWS, vous devez déjà gérer les identifiants AWS IAM pour provisionner et mettre à jour le cluster. En utilisant AWS IAM Authenticator for Kubernetes, vous évitez d'avoir à gérer un identifiant séparé pour l'accès à Kubernetes. AWS IAM offre également un certain nombre de propriétés intéressantes, telles qu'une piste d'audit hors bande (via CloudTrail) et l'application de la 2FA/MFA.
Si vous construisez un installateur Kubernetes sur AWS, AWS IAM Authenticator for Kubernetes peut simplifier votre processus de bootstrap.
Vous n'aurez pas à faire sortir clandestinement votre identifiant administrateur initial de votre cluster nouvellement installé.
Au lieu de cela, vous pouvez créer un rôle dédié KubernetesAdmin lors du provisionnement du cluster et configurer Authenticator pour autoriser les connexions des administrateurs de cluster.
En supposant que vous ayez un cluster en cours d'exécution sur AWS et que vous souhaitiez ajouter la prise en charge d'AWS IAM Authenticator for Kubernetes, vous devez :
Tout d'abord, vous devez créer un ou plusieurs rôles IAM qui seront mappés à des utilisateurs/groupes dans votre cluster Kubernetes. Le moyen le plus simple de procéder est de vous connecter à la console AWS :
Cela créera un rôle IAM sans autorisations qui peut être assumé par des utilisateurs/rôles autorisés dans votre compte. Notez le nom de ressource Amazon (ARN) de votre rôle, dont vous aurez besoin ci-dessous.
Vous pouvez également effectuer cette opération en une seule étape à l'aide de l'AWS CLI au lieu de la console 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'
Vous pouvez également ignorer cette étape et utiliser :
- Un rôle existant (par exemple un rôle d'accès entre comptes).
- Un utilisateur IAM (voir `mapUsers` ci-dessous).
- Une instance EC2 ou un rôle fédéré (voir `mapRoles` ci-dessous).
### 2. Exécuter le serveur
Le serveur est conçu pour fonctionner sur chacun de vos nœuds maîtres en tant que DaemonSet avec le réseau de l'hôte afin de pouvoir exposer un port localhost.
Pour un exemple de configuration ConfigMap et DaemonSet, voir [`deploy/example.yaml`](https://github.com/kubernetes-sigs/aws-iam-authenticator/blob/HEAD/deploy/example.yaml).
Avant de l'appliquer, mettez à jour ces valeurs pour votre cluster :
- Remplacez les ARN IAM factices (`arn:aws:iam::000000000000:...`) dans `config.yaml`.
- Définissez `clusterID` sur une valeur unique pour votre cluster.
- Vérifiez que les règles de planification du DaemonSet correspondent aux labels/taints de vos nœuds du plan de contrôle.
Ensuite, déployez-le :```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
Une fois que le pod est exécuté sur un nœud du plan de contrôle, la commande aws-iam-authenticator server créera le kubeconfig du webhook sur l'hôte à l'emplacement /etc/kubernetes/aws-iam-authenticator/kubeconfig.yaml (ou le chemin configuré via --generate-kubeconfig).
Si vous créez un installeur automatisé, vous pouvez également pré-générer facilement les fichiers de certificat, de clé et de kubeconfig du webhook à l'aide de aws-iam-authenticator init.
Cette commande générera les fichiers et les placera dans les répertoires de sortie configurés.
Vous pouvez exécuter cette commande sur chaque nœud maître avant de démarrer le serveur API. Vous pouvez également les générer avant de provisionner les nœuds maîtres et les installer dans les chemins hôtes appropriés.
Si vous ne pré-générez pas les fichiers, aws-iam-authenticator server les générera à la demande.
Cela fonctionne, mais nécessite de redémarrer votre serveur API Kubernetes après l'installation.
L'API Kubernetes s'intègre à AWS IAM Authenticator for Kubernetes à l'aide d'un webhook d'authentification par jeton.
Lorsque vous exécutez aws-iam-authenticator server, il générera un fichier de configuration du webhook et l'enregistrera sur le système de fichiers de l'hôte.
Vous devrez ajouter une seule option supplémentaire à la configuration de votre serveur API :```
--authentication-token-webhook-config-file=/etc/kubernetes/aws-iam-authenticator/kubeconfig.yaml
Sur de nombreux clusters, le serveur API s'exécute en tant que pod statique.
Vous pouvez ajouter le flag à `/etc/kubernetes/manifests/kube-apiserver.yaml`.
Assurez-vous que le répertoire hôte `/etc/kubernetes/aws-iam-authenticator/` soit monté dans votre pod serveur API.
Vous devrez peut-être aussi redémarrer le démon kubelet sur votre nœud maître pour prendre en compte la définition de pod statique mise à jour:```
systemctl restart kubelet.service
Le comportement par défaut du serveur est de récupérer les correspondances exclusivement depuis les champs mapUsers et mapRoles de son fichier de configuration. Voir Format complet de configuration ci-dessous pour plus de détails.
En utilisant le drapeau --backend-mode, vous pouvez configurer le serveur pour récupérer les correspondances depuis deux backends supplémentaires : une ConfigMap de style EKS (--backend-mode=EKSConfigMap) ou des ressources personnalisées IAMIdentityMapping (--backend-mode=CRD). Le backend par défaut, le fichier de configuration du serveur monté par le pod serveur, correspond à --backend-mode=MountedFile.
Vous pouvez passer une liste de ces backends séparés par des virgules pour que le serveur les recherche dans l'ordre. Par exemple, avec --backend-mode=EKSConfigMap,MountedFile, le serveur recherchera d'abord les correspondances dans la ConfigMap de style EKS puis, s'il ne trouve pas de correspondance pour le rôle/utilisateur IAM donné, dans le fichier de configuration du serveur. Si une correspondance pour le même rôle/utilisateur IAM existe dans plusieurs backends, le serveur utilisera la correspondance du backend qui apparaît en premier dans la liste séparée par des virgules. Dans cet exemple, si une correspondance est trouvée dans la ConfigMap EKS, elle sera utilisée qu'une correspondance en double ou conflictuelle existe ou non dans le fichier de configuration du serveur.
Notez que lorsqu'un seul backend est défini, le serveur se fournira uniquement à partir de celui-ci et ignorera les autres, même s'ils existent. Par exemple, avec --backend-mode=CRD, le serveur se fournira uniquement à partir des IAMIdentityMappings et ignorera le fichier monté et la ConfigMap EKS.
MountedFileC'est le backend par défaut des correspondances et il est suffisant pour la plupart des utilisateurs. Voir Format complet de configuration ci-dessous pour plus de détails.
CRD (alpha)Ce backend modélise chaque correspondance IAM comme une ressource personnalisée Kubernetes IAMIdentityMapping. Cette approche vous permet de maintenir les correspondances de manière native Kubernetes en utilisant kubectl ou l'API. De plus, les erreurs de syntaxe (comme un YAML mal aligné) peuvent être plus facilement détectées et n'affecteront pas toutes les correspondances.
Pour configurer un CRD IAMIdentityMapping, vous devrez d'abord apply le manifeste du CRD :```
kubectl apply -f deploy/iamidentitymapping.yaml
Une fois les CRD déployées, vous pouvez ensuite créer des ressources personnalisées qui modélisent vos identités IAM. Voir
[`./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
EKSConfigMapLa ConfigMap kube-system/aws-auth au format EKS sert de backend. La
ConfigMap doit être exactement au même format que dans les clusters EKS :
https://docs.aws.amazon.com/eks/latest/userguide/add-user-role.html. Ceci est
utile si vous migrez depuis/vers EKS et souhaitez conserver vos mappages, ou si
vous exécutez EKS en plus d'un ou de plusieurs autres clusters AWS et souhaitez
avoir les mêmes mappages dans chacun d'eux.
DynamicFileUn fichier local spécifié par cfg.dynamicfilepath peut servir de backend. Le contenu du fichier doit être exactement au même format que celui de l'EKSConfigMap. Dès que le contenu de ce fichier change, l'authenticator le recharge automatiquement. Cela offre plus de flexibilité pour la gestion des mappages ARN.
Consultez https://github.com/kubernetes-sigs/aws-iam-authenticator/blob/master/hack/dev/authenticator_with_dynamicfile_mode.yaml pour savoir comment configurer le mode DynamicFile.
Exécutez make e2e RUNNER=kind pour jouer avec un cluster kind avec le mode DynamicFile activé.
L'aws-iam-authenticator peut prendre en charge un préfixe réservé pour le nom d'utilisateur k8s. Si le préfixe réservé est défini, le nom d'utilisateur avec le préfixe réservé ne sera pas authentifié et renverra l'erreur « username must not begin with with the following prefixes: ».
Consultez https://github.com/kubernetes-sigs/aws-iam-authenticator/blob/master/hack/dev/authenticator_with_dynamicfile_mode.yaml pour savoir comment configurer le préfixe réservé.
Enfin, une fois le serveur configuré, vous voudrez vous authentifier.
Vous aurez toujours besoin d'un kubeconfig contenant les données publiques sur votre cluster (certificat CA du cluster, adresse du endpoint).
La section users de votre configuration, cependant, doit inclure une section exec (reportez-vous à la documentation des plugins d'identifiants kubectl) :```yaml
users:
Cela signifie que le `kubeconfig` est entièrement une donnée publique et peut être partagé entre tous les utilisateurs d'Authenticator.
Il peut être judicieux de le téléverser vers un emplacement public de confiance tel que AWS S3.
Assurez-vous d'avoir le binaire `aws-iam-authenticator` installé.
Vous pouvez l'installer avec `go install sigs.k8s.io/aws-iam-authenticator/cmd/aws-iam-authenticator@latest`.
Pour vous authentifier, exécutez `kubectl --kubeconfig /path/to/kubeconfig" [...]`.
kubectl exécutera `exec` le binaire `aws-iam-authenticator` avec les paramètres fournis dans votre kubeconfig, ce qui générera un jeton et le passera à l'apiserver.
Le jeton est valide pendant 15 minutes (la valeur la plus courte autorisée par AWS) et peut être réutilisé plusieurs fois.
Vous pouvez également spécifier un nom de session lors de la génération du jeton en incluant le paramètre `--session-name or -s`. Ce paramètre ne peut pas être utilisé avec `--forward-session-name`.
Vous pouvez également omettre `-r ROLE_ARN` pour signer le jeton avec vos identifiants existants sans assumer un rôle dédié.
Cela est utile si vous souhaitez vous authentifier directement en tant qu'utilisateur IAM ou si vous souhaitez vous authentifier à l'aide d'un rôle d'instance EC2 ou d'un rôle fédéré.
## Utilisation avec Kops
Les clusters gérés par [Kops](https://github.com/kubernetes/kops) peuvent être configurés pour utiliser Authenticator. Pour les instructions d'utilisation, consultez la [documentation Kops](https://kops.sigs.k8s.io/authentication/#aws-iam-authenticator).
## Comment cela fonctionne-t-il ?
Il fonctionne à l'aide du point de terminaison API AWS [`sts:GetCallerIdentity`](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetCallerIdentity.html).
Ce point de terminaison renvoie des informations sur les identifiants AWS IAM que vous utilisez pour vous y connecter.
#### Côté client (`aws-iam-authenticator token`)
Nous utilisons cette API d'une manière assez inhabituelle en faisant générer et pré-signer une requête au point de terminaison par le client Authenticator.
Nous sérialisons cette requête en un jeton qui peut traverser le système d'authentification Kubernetes.
#### Côté serveur (`aws-iam-authenticator server`)
Le jeton est transmis via le serveur API Kubernetes et vers le point de terminaison `/authenticate` du serveur Authenticator par une configuration de webhook.
Le serveur Authenticator valide tous les paramètres de la requête pré-signée pour s'assurer que rien ne semble suspect.
Il soumet ensuite la requête au vrai serveur `https://sts.amazonaws.com`, qui valide la signature HMAC du client et renvoie des informations sur l'utilisateur.
Maintenant que le serveur connaît l'identité AWS du client, il traduit cette identité en un utilisateur Kubernetes et des groupes via un mappage statique simple.
Ce mécanisme est emprunté, avec quelques modifications, à [Vault](https://www.vaultproject.io/docs/auth/aws.html#iam-auth-method).
## Qu'est-ce qu'un ID de cluster ?
L'ID de cluster Authenticator est un identifiant unique par cluster qui empêche certaines attaques par rejeu.
Plus précisément, il empêche un serveur Authenticator (par exemple, dans un environnement de développement) d'utiliser le jeton d'un client pour s'authentifier auprès d'un autre serveur Authenticator dans un autre cluster.
L'ID de cluster doit bien être unique par cluster, mais il n'a pas besoin d'être secret.
Quelques bons choix sont :
- Un ID aléatoire tel que celui généré par `openssl rand 16 -hex`
- Le nom de domaine de votre serveur API Kubernetes
La [documentation Vault](https://www.vaultproject.io/docs/auth/aws.html#iam-auth-method) explique également cette attaque (voir `X-Vault-AWS-IAM-Server-ID`).
## Spécification des identifiants et utilisation des profils AWS
Les identifiants peuvent être spécifiés pour une utilisation avec `aws-iam-authenticator` via l'une des méthodes disponibles dans le
[AWS SDK pour Go](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials).
Cela inclut la spécification des identifiants AWS avec des variables d'environnement ou l'utilisation d'un fichier d'identifiants.
Les [profils nommés](https://docs.aws.amazon.com/cli/latest/userguide/cli-multiple-profiles.html) AWS sont pris en charge par `aws-iam-authenticator`
via la variable d'environnement `AWS_PROFILE`. Par exemple, pour vous authentifier avec les identifiants spécifiés dans le profil _dev_, `AWS_PROFILE` peut
être exporté ou spécifié explicitement (par exemple, `AWS_PROFILE=dev kubectl get all`). Si aucun `AWS_PROFILE` n'est défini, le profil _default_ est utilisé.
`AWS_PROFILE` peut également être spécifié directement dans le fichier kubeconfig
[comme partie du flux `exec`](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#configuration). Par exemple, pour spécifier
que les identifiants du profil nommé _dev_ doivent toujours être utilisés par `aws-iam-authenticator`, votre kubeconfig inclurait une clé `env`
qui définit le profil :```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"
Cette méthode permet d'utiliser le profil approprié implicitement. Notez que toute variable d'environnement définie dans le cadre du flux exec prendra le pas sur ce qui est déjà défini dans votre environnement.
Les utilisateurs AWS fédérés ont souvent un attribut « significatif » mappé sur leur rôle assumé, comme une adresse e-mail, via la configuration AWS du compte.
Ces sessions assumées comportent quelques éléments, le role id
et caller-specified-role-name. Par défaut, lorsqu'un utilisateur fédéré utilise l'option --role de aws-iam-authenticator pour assumer un nouveau rôle, le
caller-specified-role-name est converti en un jeton aléatoire et le role id est conservé dans le rôle nouvellement assumé.
L'utilisation de aws-iam-authenticator token ... --forward-session-name mappera l'attribut d'origine caller-specified-role-name sur la nouvelle session assumée STS.
Cela peut être utile pour tenter d'associer rapidement « qui a effectué l'action X sur le cluster K8 ».
Veuillez noter que cela ne doit pas être considéré comme définitif et doit être recoupé via le role id (qui reste cohérent) avec les journaux CloudTrail,
car un utilisateur pourrait potentiellement modifier cela côté client.
Il est possible d'effectuer des requêtes vers l'API Kubernetes depuis un client situé à l'extérieur du cluster, que ce soit en utilisant
l'API REST Kubernetes brute ou l'un des clients Kubernetes spécifiques à un langage
(par exemple, Python). Pour ce faire, vous devez créer un jeton porteur qui
est inclus avec la requête adressée à l'API. Ce jeton porteur nécessite que vous ajoutiez la chaîne k8s-aws-v1. avec une
chaîne encodée en base64 d'une requête HTTP signée adressée à l'API STS GetCallerIdentity Query. Ceci est ensuite envoyé dans
l'en-tête Authorization de la requête. Il est toutefois à noter que l'authentificateur IAM omet explicitement
le remplissage base64 pour éviter tout caractère =, garantissant ainsi une chaîne sûre à utiliser dans les URL. Voici ci-dessous un exemple en
Python de la manière dont ce jeton serait construit :```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')}
## Dépannage
Si votre client échoue avec une erreur comme `could not get token: AccessDenied [...]`, vous pouvez essayer d'assumer le rôle directement avec l'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 cela échoue, il y a quelques problèmes possibles à vérifier :
Assurez-vous que vos identifiants AWS de base sont disponibles dans votre shell (aws sts get-caller-identity peut vous aider à diagnostiquer ce problème).
Assurez-vous que le rôle cible autorise l'accès depuis votre compte source (dans la politique de confiance du rôle).
Assurez-vous que votre principal source (utilisateur/rôle/groupe) dispose d'une politique IAM qui autorise sts:AssumeRole pour le rôle cible.
Assurez-vous de ne pas avoir de politiques de refus explicites attachées à votre utilisateur, à votre groupe ou dans AWS Organizations qui empêcheraient le sts:AssumeRole.
Essayez de simuler l'appel sts:AssumeRole dans le Policy Simulator.
Le client et le serveur ont le même format de configuration. Ils peuvent partager exactement le même fichier de configuration, car aucun secret n'est stocké dans la configuration.```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:
## Development
See the [development](https://github.com/kubernetes-sigs/aws-iam-authenticator/blob/HEAD/docs/development.md) page.
## Community, discussion, contribution, and support
Learn how to engage with the Kubernetes community on the [community page](http://kubernetes.io/community/).
You can reach the maintainers of this project at:
- [Slack](https://kubernetes.slack.com/messages/sig-aws)
- [Mailing List](https://groups.google.com/forum/#!forum/kubernetes-sig-aws)
### Code of conduct
Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](https://github.com/kubernetes-sigs/aws-iam-authenticator/blob/HEAD/code-of-conduct.md).