internet/awx-operator
3
0
Fork 0
mirror of https://github.com/ansible/awx-operator.git synced 2026-05-07 05:42:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

Standardize dev workflow with Makefile includes and developer documentation (#2111)

Browse Source 
* Add standardized Makefile includes and developer documentation

Introduce modular Makefile system (common.mk + operator.mk) for
consistent dev workflows. Standardize CONTRIBUTING.md and
docs/development.md to follow community conventions with clear
separation: contributing guidelines for process, development
guide for technical setup.

- Add common.mk with shared dev workflow targets (make up/down)
- Add operator.mk with AWX-specific variables and targets
- Restructure CONTRIBUTING.md: process, testing requirements, community links
- Expand docs/development.md: customization options table, teardown options,
  Molecule testing, bundle generation via make targets
- Simplify README.md contributing section

Assisted-by: Claude
Signed-off-by: Lucas Benedito <lbenedit@redhat.com>

* Fix DEV_IMG docs example to avoid double-tag issue

Assisted-by: Claude
Signed-off-by: Lucas Benedito <lbenedit@redhat.com>

---------

Signed-off-by: Lucas Benedito <lbenedit@redhat.com>
This commit is contained in:
Lucas Benedito
2026-04-14 12:30:17 +01:00
committed by GitHub
parent 60fc7d856c
commit 9c3f521514
8 changed files with 745 additions and 422 deletions
Download Patch File Download Diff File Expand all files Collapse all files

229
docs/development.md
View File

@@ -1,6 +1,8 @@
# Development Guide
There are development scripts and yaml examples in the [`dev/`](../dev) directory that, along with the up.sh and down.sh scripts in the root of the repo, can be used to build, deploy and test changes made to the awx-operator.
There are development yaml examples in the [`dev/`](../dev) directory and Makefile targets that can be used to build, deploy and test changes made to the awx-operator.
Run `make help` to see all available targets and options.
## Prerequisites
@@ -10,95 +12,218 @@ You will need to have the following tools installed:
* [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
* [podman](https://podman.io/docs/installation) or [docker](https://docs.docker.com/get-docker/)
* [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
* [oc](https://docs.openshift.com/container-platform/4.11/cli_reference/openshift_cli/getting-started-cli.html) (if using Openshift)
* [oc](https://docs.openshift.com/container-platform/4.11/cli_reference/openshift_cli/getting-started-cli.html) (if using OpenShift)
You will also need to have a container registry account. This guide uses quay.io, but any container registry will work. You will need to create a robot account and login at the CLI with `podman login` or `docker login`.
You will also need a container registry account. This guide uses [quay.io](https://quay.io), but any container registry will work.
## Quay.io Setup for Development
Before using the development scripts, you'll need to set up a Quay.io repository and pull secret:
## Registry Setup
### 1. Create a Private Quay.io Repository
- Go to [quay.io](https://quay.io) and create a private repository named `awx-operator` under your username
- The repository URL should be `quay.io/username/awx-operator`
### Create a Quay.io Repository
### 2. Create a Bot Account
- In your Quay.io repository, go to Settings → Robot Accounts
- Create a new robot account with write permissions to your repository
- Click on the robot account name to view its credentials
1. Go to [quay.io](https://quay.io) and create a repository named `awx-operator` under your username.
2. Login at the CLI:
```sh
podman login quay.io
```
### 3. Generate Kubernetes Pull Secret
- In the robot account details, click "Kubernetes Secret"
- Copy the generated YAML content from the pop-up
### Pull Secret (optional)
### 4. Create Local Pull Secret File
- Create a file at `hacking/pull-secret.yml` in your awx-operator checkout
- Paste the Kubernetes secret YAML content into this file
- **Important**: Change the `name` field in the secret from the default to `redhat-operators-pull-secret`
- The `hacking/` directory is in `.gitignore`, so this file won't be committed to git
If your repository is private, you'll need to configure a pull secret so the cluster can pull your operator image:
Example `hacking/pull-secret.yml`:
1. In your Quay.io repository, go to Settings → Robot Accounts.
2. Create a robot account with write permissions.
3. Click the robot account name, then click "Kubernetes Secret" and copy the YAML.
4. Save it to `hacking/pull-secret.yml` in your checkout (this path is in `.gitignore`).
5. Change the `name` field to `redhat-operators-pull-secret`.
Example:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: redhat-operators-pull-secret # Change this name
namespace: awx
name: redhat-operators-pull-secret
type: kubernetes.io/dockerconfigjson
data:
.dockerconfigjson: <base64-encoded-credentials>
```
If a pull secret file is found at `hacking/pull-secret.yml` (or the path set by `PULL_SECRET_FILE`), `make up` will apply it automatically. Otherwise, you can make your quay.io repos public or create a global pull secret on your cluster.
## Build and Deploy
Make sure you are logged into your cluster (`oc login` or `kubectl` configured), then run:
If you clone the repo, and make sure you are logged in at the CLI with oc and your cluster, you can run:
```
export QUAY_USER=username
export NAMESPACE=awx
export TAG=test
./up.sh
```sh
QUAY_USER=username make up
```
You can add those variables to your .bashrc file so that you can just run `./up.sh` in the future.
This will:
1. Login to container registries
2. Create the target namespace
3. Build the operator image and push it to your registry
4. Deploy the operator via kustomize
5. Apply dev secrets and create a dev AWX instance
> Note: the first time you run this, it will create quay.io repos on your fork. If you followed the Quay.io setup steps above and created the `hacking/pull-secret.yml` file, the script will automatically handle the pull secret. Otherwise, you will need to either make those repos public, or create a global pull secret on your cluster.
### Customization Options
To get the URL, if on **Openshift**, run:
| Variable | Default | Description |
|----------|---------|-------------|
| `QUAY_USER` | _(required)_ | Your quay.io username |
| `NAMESPACE` | `awx` | Target namespace |
| `DEV_TAG` | `dev` | Image tag for dev builds |
| `CONTAINER_TOOL` | `podman` | Container engine (`podman` or `docker`) |
| `PLATFORM` | _(auto-detected)_ | Target platform (e.g., `linux/amd64`) |
| `MULTI_ARCH` | `false` | Build multi-arch image (`linux/arm64,linux/amd64`) |
| `DEV_IMG` | `quay.io/<QUAY_USER>/awx-operator` | Override full image path (skips QUAY_USER) |
| `BUILD_IMAGE` | `true` | Set to `false` to skip image build (use existing image) |
| `CREATE_CR` | `true` | Set to `false` to skip creating the dev AWX instance |
| `CREATE_SECRETS` | `true` | Set to `false` to skip creating dev secrets |
| `IMAGE_PULL_POLICY` | `Always` | Set to `Never` for local builds without push |
| `BUILD_ARGS` | _(empty)_ | Extra args passed to container build (e.g., `--no-cache`) |
| `DEV_CR` | `dev/awx-cr/awx-openshift-cr.yml` | Path to the dev CR to apply |
| `PULL_SECRET_FILE` | `dev/pull-secret.yml` | Path to pull secret YAML |
| `PODMAN_CONNECTION` | _(empty)_ | Remote podman connection name |
```
$ oc get route
Examples:
```bash
# Use a specific namespace and tag
QUAY_USER=username NAMESPACE=awx DEV_TAG=mytag make up
# Use docker instead of podman
CONTAINER_TOOL=docker QUAY_USER=username make up
# Build for a specific platform (e.g., when on ARM building for x86)
PLATFORM=linux/amd64 QUAY_USER=username make up
# Deploy without building (use an existing image)
BUILD_IMAGE=false DEV_IMG=quay.io/myuser/awx-operator DEV_TAG=latest make up
# Build without pushing (local cluster like kind/minikube)
IMAGE_PULL_POLICY=Never QUAY_USER=username make up
```
On **k8s with ingress**, run:
### Accessing the Deployment
```
$ kubectl get ing
On **OpenShift**:
```sh
oc get route
```
On **k8s with nodeport**, run:
```
$ kubectl get svc
On **k8s with ingress**:
```sh
kubectl get ing
```
The URL is then `http://<Node-IP>:<NodePort>`
On **k8s with nodeport**:
```sh
kubectl get svc
```
The URL is then `http://<Node-IP>:<NodePort>`.
> Note: NodePort will only work if you expose that port on your underlying k8s node, or are accessing it from localhost.
> **Note**: NodePort will only work if you expose that port on your underlying k8s node, or are accessing it from localhost.
### Default Credentials
The dev CR pre-creates an admin password secret. Default credentials are:
- **Username**: `admin`
- **Password**: `password`
Without the dev CR, a password would be generated and stored in a secret named `<deployment-name>-admin-password`.
By default, the usename and password will be admin and password if using the `up.sh` script because it pre-creates a custom admin password k8s secret and specifies it on the AWX custom resource spec. Without that, a password would have been generated and stored in a k8s secret named <deployment-name>-admin-password.
## Clean up
To tear down your development deployment:
Same thing for cleanup, just run ./down.sh and it will clean up your namespace on that cluster
```
./down.sh
```sh
make down
```
## Running CI tests locally
### Teardown Options
More tests coming soon...
| Variable | Default | Description |
|----------|---------|-------------|
| `KEEP_NAMESPACE` | `false` | Set to `true` to keep the namespace for reuse |
| `DELETE_PVCS` | `true` | Set to `false` to preserve PersistentVolumeClaims |
| `DELETE_SECRETS` | `true` | Set to `false` to preserve secrets |
Examples:
```bash
# Keep the namespace for faster redeploy
KEEP_NAMESPACE=true make down
# Keep PVCs (preserve database data between deploys)
DELETE_PVCS=false make down
```
## Testing
### Linting
Run linting checks (required for all PRs):
```sh
make lint
```
This runs `ansible-lint` on roles, playbooks, and config samples, and checks that `no_log` statements use the `{{ no_log }}` variable.
### Molecule Tests
The operator includes a [Molecule](https://ansible.readthedocs.io/projects/molecule/)-based test environment for integration testing. Molecule can run standalone in Docker or inside a Kubernetes cluster.
Install Molecule:
```sh
python -m pip install molecule-plugins[docker]
```
#### Testing in Kind (recommended)
[Kind](https://kind.sigs.k8s.io/docs/user/quick-start/) is the recommended way to test locally:
```sh
molecule test -s kind
```
#### Testing in Minikube
```sh
minikube start --memory 8g --cpus 4
minikube addons enable ingress
molecule test -s test-minikube
```
[Minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/) runs a full VM with an assigned IP address, making it easier to test NodePort services and Ingress from outside the cluster.
Once deployed, access the AWX UI:
1. Add `<minikube-ip> example-awx.test` to your `/etc/hosts` file (get the IP with `minikube ip`).
2. Visit `http://example-awx.test/` (default login: `test`/`changeme`).
#### Active Development
Use `molecule converge` instead of `molecule test` to keep the environment running after tests complete — useful for iterating on changes.
## Bundle Generation
If you have the Operator Lifecycle Manager (OLM) installed, you can generate and deploy an operator bundle:
```bash
# Generate bundle manifests and validate
make bundle
# Build and push the bundle image
make bundle-build bundle-push
# Build and push a catalog image
make catalog-build catalog-push
```
After pushing the catalog, create a `CatalogSource` in your cluster pointing to the catalog image. Once the CatalogSource is in a READY state, the operator will be available in OperatorHub.