How to AWX

How to AWX

How to AWX

Documentation: docs.ansible.com/ansible-tower/latest/html/userguide/overview.html
Repository: github.com/ansible/awx

AWX est une interface web et REST pour l’outil d’automatisation ansible.

Installation

À partir de 18.0 il est recommandé de l’installer à travers AWX Operator qui dépend de kubernetes. Il est aussi possible d’utiliser une image docker.

Kubernetes

Documentation: https://ansible.readthedocs.io/projects/awx-operator/en/latest/installation/basic-install.html

Déploiement de AWX Operator sur un cluster Kubernetes :

On utilise kustomize pour assembler et appliquer les configurations yaml Kubernetes.
Il faut une storage class fonctionnelle dans le cluster.

Remarques :

On peut aussi utiliser un chart helm pour l’opérateur uniquement : https://ansible.readthedocs.io/projects/awx-operator/en/latest/installation/helm-install-on-existing-cluster.html
Si vous n’avez pas de cluster Kubernetes, on peut facilement en créer un cluster mono-neud avec k3s par exemple voir HowtoK3s

Nous allons créer un dossier awx contenant la configuration pour l’opérateur, une instance et traefik (ingress) :

$ tree -L 3 awx
awx
├── kustomization.yaml
├── awx-instances
│   ├── demo
│   │   ├── awx-instance.yaml
│   │   ├── kustomization.yaml
│   │   └── traefik-ingressroute.yaml
│   └── kustomization.yaml
└── awx-operator
    └── kustomization.yaml

un fichier kustomize qui va assembler tout awx/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ./awx-operator
  - ./awx-instances

L’opérateur awx/awx-operator/kustomization.yaml qui va être créé dans le namespace awx

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  # Prendre le dernier release tag : https://github.com/ansible/awx-operator/releases
  - github.com/ansible/awx-operator/config/default?ref=2.10.0
# Set the image tags to match the git version from above
images:
  # le tag de l'image doit etre le meme que celui du release tag ci-dessus
  - name: quay.io/ansible/awx-operator
    newTag: 2.10.0

# Specifier le namespace de awx
namespace: awx

Une instance…

# awx/awx-instances/demo/kustomization.yaml 
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - awx-instance.yaml
  - traefik-ingressroute.yaml

# awx/awx-instances/demo/awx-instance.yaml 
apiVersion: awx.ansible.com/v1beta1
kind: AWX
metadata:
  name: awx-demo
spec:
  service_type: clusterip

# awx/awx-instances/demo/traefik-ingressroute.yaml
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: demo-instance-awx
spec:
  entryPoints:
    - websecure
  routes:                           
  - kind: Rule
    match: Host(`awx.chez-vous.org`)
    services:
    - kind: Service
      name: awx-demo-service
      port: 80
  tls:
    certResolver: letsencrypt

on peut aussi configurer directement les paramètres de l’insgress dans le spec de l’instance, voir documentation : https://ansible.readthedocs.io/projects/awx-operator/en/latest/user-guide/network-and-tls-configuration.html

Lancer le Déploiement :

$ kubectl apply -k awx
namespace/awx created
customresourcedefinition.apiextensions.k8s.io/awxbackups.awx.ansible.com created
customresourcedefinition.apiextensions.k8s.io/awxrestores.awx.ansible.com created
customresourcedefinition.apiextensions.k8s.io/awxs.awx.ansible.com created
serviceaccount/awx-operator-controller-manager created
role.rbac.authorization.k8s.io/awx-operator-awx-manager-role created
role.rbac.authorization.k8s.io/awx-operator-leader-election-role created
clusterrole.rbac.authorization.k8s.io/awx-operator-metrics-reader created
clusterrole.rbac.authorization.k8s.io/awx-operator-proxy-role created
rolebinding.rbac.authorization.k8s.io/awx-operator-awx-manager-rolebinding created
rolebinding.rbac.authorization.k8s.io/awx-operator-leader-election-rolebinding created
clusterrolebinding.rbac.authorization.k8s.io/awx-operator-proxy-rolebinding created
configmap/awx-operator-awx-manager-config created
service/awx-operator-controller-manager-metrics-service created
deployment.apps/awx-operator-controller-manager created

Voir ou en est l’installation

$ kubectl -n awx logs -f deployments/awx-operator-controller-manager
# suivre le lancement d'instance(s)
$ kubectl logs -n awx -f deployments/awx-operator-controller-manager -c awx-manager
# Récuperer le mot de passe d'une instance
$ kubectl get secret -n awx awx-demo-admin-password -o jsonpath="{.data.password}" | base64 --decode ; echo

Si tout se passe bien, on

Docker (Déprécié)

Copier le dépôt sur le serveur a partir d’une version stable: https://github.com/ansible/awx/releases/tag

Il faudra installer les paquets suivants:

python3
python3-venv
python3-setuptools-scm
python3-psycopg2
ansible
docker-compose

Le dépôt devra appartenir a l’usager exécutant, il faut s’assurer que les programmes dans le dossier tools ont bien un droit d’exécution. (Faire attention a noexec qui peut remonter jusqu’au conteneur dans certains cas)

Une fois les prérequis installée et les permissions bien appliquée, on peut continuer avec l’installation:

La documentation complète se situe sur Github

$ make docker-compose-build $ make docker-compose

Suite a la complétion, on peut lancer dans un autre terminal:

$ docker exec tools_awx_1 make clean-ui ui-devel

On peut ensuite accéder a l’interface sur https://localhost:8043/#/home

CLI

Une interface de ligne de commande peut aussi être installé directement sur l’hôte

$ pip3 install awxkit

Doc

La documentation peut être installé en local

$ pip3 install sphinx sphinxcontrib-autoprogram
$ cd awxkit/awxkit/cli/docs
$ TOWER_HOST=https://awx.example.org TOWER_USERNAME=example TOWER_PASSWORD=secret make clean html
$ cd build/html/ && python -m http.server
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ..

Configuration

Créer un nouvel admin

$ docker exec -ti tools_awx_1 awx-manage createsuperuser

Utiliser un postgres externe

Il faut aller indiquer le postgres désiré dans les variables de tools/docker-compose/inventory

Migration

Doc officielle https://ansible.readthedocs.io/projects/awx-operator/en/latest/migration/migration.html

On peut migrer en utilisant la doc officielle au sain d’un même cluster kube. Autrement si on migre en 2 cluster kube q distincs, il faut adapter un peu la documentation :

Créer l’instance vierge sur la nouvelle machine avec son dossier d’instance kustomize … puis la détruire (simplement kubectl delete le kind awx)
Recréer le secret <resourcename>-secret-key en y mettant celui de l’ancien
Éditer/recréer la configmap pour postgres et y mettre celui de l’ancien
Copier le datadir de postgres
Recréer le kind awx/l’instance, c’est tout bon

FAQ

Les fichiers temporaire d’AWX prennent trop d’inodes

Si les fichiers temporaire d’AWX prennent trop d’inode, il faut relancer les conteneur du pod .*-task-.*, mais avant tout il faut s’asusrer qu’aucun job AWX ne soit en cours ou lancer dans les prochaines minutes, autrement il vont échouer.

Pour effectuer ça il faut lancer un rollout sur le pod en question comme ceci :

# k3s crictl ps
CONTAINER           IMAGE               CREATED             STATE               NAME                     ATTEMPT             POD ID              POD                                                NAMESPACE
d874a6c817f4d       87ab0ba4bf682       23 minutes ago      Running             foo-rsyslog             0                   94227556ad5f7       foo-task-78446dccfb-98xwl                         awx
233d857520cde       f5df180d3d593       23 minutes ago      Running             foo-ee                  0                   94227556ad5f7       foo-task-78446dccfb-98xwl                         awx
b76d209cfa434       87ab0ba4bf682       23 minutes ago      Running             foo-task                0                   94227556ad5f7       foo-task-78446dccfb-98xwl                         awx
6f9ad454c4c02       a7f6d19aede6b       23 minutes ago      Running             redis                   0                   94227556ad5f7       foo-task-78446dccfb-98xwl                         awx
[...]
# kubectl -n awx rollout restart deploy/foo-task

Pour éviter que ça se repoduise, il faut dans l’UI d’AWX, s’assurer que tmp dir cleanup soit activé.