AWX in Action

Projects: Where Your Playbooks Live

A project is a logical collection of Ansible playbooks. It's a way to organize your Ansible content and make it available to AWX. Projects are the building blocks of automation in AWX. They let you manage your playbooks, roles, and any other files needed to run your automation tasks.

To test this feature, let's explore the Projects menu. Click on Add to create a new project. You should provide the following information:

• Name: The name of the project.

• Description: A brief description of the project.

• Organization: The organization to which the project belongs.

• Execution Environment: The execution environment that will be used to run the playbooks in the project. Based on the organization you choose, a list of execution environments available to that organization will be displayed.

• Source Control Type: The type of source control system that will be used to store the project files. You can use Git, Manual, Subversion and others.

• Content Signature Validation Credentials: Used to verify that the content has remained secure when a project is synced. If the content has been tampered with, the job will not run.

Creating a Manual Project (PV-Backed)

This section will guide you through creating a manual project.

A manual project is one that is created without using a source control system like Git or Subversion (SVN). Since we are running AWX in a Kubernetes cluster, we should know in advance where the playbooks should be stored. In Kubernetes, containers are ephemeral; any data stored in the container will be lost when the container is removed or restarted. Therefore, AWX uses a Persistent Volume (PV) to store the project files. This volume is mounted to the container, and the files are kept outside of the container (for example, on the host machine or a cloud storage service). To list the volumes available in the cluster, you can run the following command:

kubectl -n awx get pv

You should see a list of volumes available in the cluster. Typically, you'll find two named awx-projects-volume and awx-postgres-15-volume. The awx-projects-volume is used to store project files.

To get more information about the volume, use the following command:

kubectl -n awx describe pv awx-projects-volume

You should see information about the volume, including its capacity, access modes, and the path where the volume is mounted.

Example output:

Name:            awx-projects-volume
Labels:          
Annotations:     pv.kubernetes.io/bound-by-controller: yes
Finalizers:      [kubernetes.io/pv-protection]
StorageClass:    awx-projects-volume
Status:          Bound
Claim:           awx/awx-projects-claim
Reclaim Policy:  Retain
Access Modes:    RWO
VolumeMode:      Filesystem
Capacity:        2Gi
Node Affinity:   
Message:         
Source:
    Type:          HostPath (bare host directory volume)
    Path:          /data/projects
    HostPathType:  
Events:            

We can see that the volume is mounted to the /data/projects path on the host machine (Type: HostPath). This is where we will store the project files. You should see the same output unless you have changed the default configuration when deploying AWX using K3s.

Store the path in a variable for easier access:

# Export the projects path
export PROJECTS_PATH=$(\
  kubectl -n awx get pv awx-projects-volume \
  -o jsonpath='{.spec.hostPath.path}')

# Export the path to .bashrc
echo "export PROJECTS_PATH=$PROJECTS_PATH" >> $HOME/.bashrc

# Source the .bashrc file
source $HOME/.bashrc

Let's create a sample playbook to use in the project. Start by creating a folder for it:

mkdir -p $PROJECTS_PATH/uptime

Create a playbook:

cat < $PROJECTS_PATH/uptime/up.yml
---
- name: Check uptime
  hosts: all
  tasks:
    - name: Get uptime
      command: uptime
    register: uptime

    - name: Print uptime
      debug:
        msg: "This node has been up for {{ uptime.stdout }}"
EOF

This playbook checks the uptime of the host and prints the result. Let's create a manual project in AWX to store this playbook. Follow these steps:

• Go to the Projects menu and click on Add.
• Provide the following information:
• Name: Uptime
• Description: Check the uptime of the host
• Organization: Solara
• Source Control Type: Manual
• Execution Environment: Leave the default execution environment.
• Click on Save to create the project. You should now see the project in the list of projects.

Make sure that the Pod now has access to the project files. You can check this by running the following command:

# Check that the uptime project has been added
kubectl -n awx exec -it deployment/awx-web \
  -c awx-web -- ls -l /var/lib/awx/projects

# Check that the uptime playbook has been added to the project
kubectl -n awx exec -it deployment/awx-web \
  -c awx-web -- ls -l /var/lib/awx/projects/uptime

Creating a Git-Backed Project

In this section, we'll see how to create a project that is synced with a Git repository. This is useful for larger projects where you want to track changes and collaborate with other team members.

Start by installing the Git package on the AWX machine:

dnf install -y git

Install the GitHub CLI:

dnf install 'dnf-command(config-manager)'

dnf config-manager --add-repo \
  https://cli.github.com/packages/rpm/gh-cli.repo

dnf install gh --repo gh-cli -y

Before starting, you need to authenticate with GitHub. Go to your GitHub account and generate a new token. Make sure to select the repo and admin:public_key scopes to activate the necessary permissions.

Export the following variables and save them in your .bashrc file for future use:

# Export the GitHub token and other variables
export GH_TOKEN=
export GH_USER=
export GH_EMAIL=

# Save the variables in the .bashrc file
cat <> ~/.bashrc && source ~/.bashrc
export GH_TOKEN=$GH_TOKEN
export GH_USER=$GH_USER
export GH_EMAIL=$GH_EMAIL
EOF

Let's create a new repository using the GitHub CLI:

gh repo create demo-ansible-playbooks --private

This creates a new private repository named demo-ansible-playbooks. You can also create a repository from the GitHub website if you prefer.

Create a new folder and initialize a new Git repository:

mkdir -p $PROJECTS_PATH/demo-ansible-playbooks
cd $PROJECTS_PATH/demo-ansible-playbooks
git init

Create a sample playbook:

cat < $PROJECTS_PATH/demo-ansible-playbooks/playbook.yml
---
- name: Install epel-release
  hosts: all
  tasks:
    - name: Install epel-release
      yum:
        name: epel-release
        state: present
EOF

Stage the changes:

git add .

Add an author identity, change the branch name to main, and add the remote repository:

# Add an author identity
git config --global user.email "$GH_EMAIL"
git config --global user.name "$GH_USER"

# Change the branch name to main
git branch -M main

# Add the remote repository
git remote add origin git@github.com:$GH_USER/demo-ansible-playbooks.git

Commit the changes:

git commit -m "Initial commit"

Before pushing the changes, you need to add your SSH key to your GitHub account. We're going to use the same SSH key generated earlier since we're working in a lab environment and don't have strict security requirements. For tighter security, you may want to generate a dedicated SSH key for this purpose. Run the following GH CLI command to add your SSH key:

gh ssh-key add ~/.ssh/id_rsa.pub --title "AWX"

Let's use a .gitignore file to exclude files that you don't want to track:

cat < $PROJECTS_PATH/demo-ansible-playbooks/.gitignore
# Ignore Linux system files
*.swp
*~
# Ignore Ansible artifacts
*.retry
# Ignore Python virtual environment
venv/
EOF

Now you can push the changes to the remote repository:

git push -u origin main

When creating playbooks, it's a good practice to create tags for each version. This will help you keep track of changes and roll back to a previous version if needed. Create a tag for the initial commit:

git tag -a v1.0 -m "Initial commit"
git push origin v1.0

Now, return to the AWX web interface and follow these steps:

• Go to the Credentials menu and click on Add.
• Choose the Source Control type as Git and provide the following information:
• Name: GitHub (Solara)
• Description: GitHub credentials for Solara
• Organization: Solara
• Credential Type: Keep it as Source Control
• SCM Private Key: Add the private key you generated earlier (cat $HOME/.ssh/id_rsa)
• Click on Save to create the credential.