Skip to content

Standardize dev workflow with Makefile includes and developer documentation #335

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lucas-benedito wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Standardize dev workflow with Makefile includes and developer documentation #335

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c80f3fc
Add standardized Makefile includes and developer documentation
lucas-benedito Mar 26, 2026
597ddad
Address PR review feedback for Makefile standardization
lucas-benedito Apr 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 33 additions & 46 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,66 +1,53 @@
# Contributing
# Contributing to EDA Server Operator

Hi there! We're excited to have you as a contributor.

## Development Environment
Have questions about this document or anything not covered here? Please file an issue at [https://github.com/ansible/eda-server-operator/issues](https://github.com/ansible/eda-server-operator/issues).

There are a couple ways to make and test changes to an Ansible operator. The easiest way is to build and deploy the operator from your branch using the make targets. This is closed to how the operator will be used, and is what is documented below. However, it may be useful to run the EDA Operator roles directly on your local machine for faster iteration. This involves a bit more set up, and is described in the [Debugging docs](./docs/debugging.md).
## Things to know prior to submitting code

First, you need to have a k8s cluster up. If you don't already have a k8s cluster, you can use minikube to start a lightweight k8s cluster locally by following these [minikube test cluster docs](./docs/minikube-test-cluster.md).
- All code submissions are done through pull requests against the `main` branch.
- All PRs must have a single commit. Make sure to `squash` any changes into a single commit.
- Take care to make sure no merge commits are in the submission, and use `git rebase` vs `git merge` for this reason.
- If collaborating with someone else on the same branch, consider using `--force-with-lease` instead of `--force`. This will prevent you from accidentally overwriting commits pushed by someone else. For more information, see [git push --force-with-lease](https://git-scm.com/docs/git-push#git-push---force-with-leaseltrefnamegt).
- We ask all of our community members and contributors to adhere to the [Ansible code of conduct](http://docs.ansible.com/ansible/latest/community/code_of_conduct.html). If you have questions, or need assistance, please reach out to our community team at [codeofconduct@ansible.com](mailto:codeofconduct@ansible.com).

## Setting up your development environment

See [docs/development.md](docs/development.md) for prerequisites, build/deploy instructions, and available Makefile targets.

### Build Operator Image
For faster iteration, you can also run the EDA Operator roles directly on your local machine. See the [Debugging docs](docs/debugging.md) for details.

Clone the eda-server-operator
## Submitting your work

1. From your fork's `main` branch, create a new branch to stage your changes.
```sh
git checkout -b <branch-name>
```
git clone git@github.com:ansible/eda-server-operator.git
2. Make your changes.
3. Test your changes (see [Testing](#testing) below).
4. Commit your changes.
```sh
git add <FILES>
git commit -m "My message here"
```
5. Create your [pull request](https://github.com/ansible/eda-server-operator/pulls).

Create an image repo in your user called `eda-server-operator` on [quay.io](https://quay.io) or your preferred image registry.
> **Note**: If you have multiple commits, make sure to `squash` them into a single commit before submitting.

Build & push the operator image
## Testing

```
export QUAY_USER=username
export TAG=feature-branch
make docker-build docker-push IMG=quay.io/$QUAY_USER/eda-server-operator:$TAG
```


### Deploy EDA Operator
All changes must be tested before submission:

- **Linting** (required for all PRs): `make lint`
- See the [Testing section in docs/development.md](docs/development.md#testing) for details on running tests locally.

1. Log in to your K8s or Openshift cluster.
## Reporting Issues

```
kubectl login <cluster-url>
```
We welcome your feedback, and encourage you to file an issue when you run into a problem at [https://github.com/ansible/eda-server-operator/issues](https://github.com/ansible/eda-server-operator/issues).

2. Run the `make deploy` target
## Getting Help

```
NAMESPACE=eda IMG=quay.io/$QUAY_USER/eda-server-operator:$TAG make deploy
```
> **Note** The `latest` tag on the quay.io/ansible/eda-server-operator repo is the latest _released_ (tagged) version and the `main` tag is built from the HEAD of the `main` branch. To deploy with the latest code in `main` branch, check out the main branch, and use `IMG=quay.io/ansible/eda-server-operator:main` instead.
### Forum


### Create an EDA CR

Create a yaml file defining the EDA custom resource

```yaml
# eda.yaml
apiVersion: eda.ansible.com/v1alpha1
kind: EDA
metadata:
name: my-eda
spec:
automation_server_url: https://awx-host
```

3. Now apply this yaml

```bash
$ kubectl apply -f eda.yaml
```
Join the [Ansible Forum](https://forum.ansible.com) for questions, help, and development discussions. Search for posts tagged with [`eda`](https://forum.ansible.com/tag/eda) or start a new discussion.
94 changes: 47 additions & 47 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,7 @@
# To re-generate a bundle for another specific version without changing the standard setup, you can:
# - use the VERSION as arg of the bundle target (e.g make bundle VERSION=0.0.2)
# - use environment variables to overwrite this value (e.g export VERSION=0.0.2)
VERSION ?= 0.0.1

# Default ENGINE for building the operator (default docker)
ENGINE ?= docker
# VERSION ?= 0.0.1 # Set in operator.mk
Copy link
Copy Markdown
Member

@AlexSCorey AlexSCorey Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need to keep this in?

Copy link
Copy Markdown
Member Author

@lucas-benedito lucas-benedito Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For now, I will keep it. The next Makefile update that we do (it will happen on all operators) then I can drop the commented out value from the operator-sdk sourced Makefile.
I only kept to ensure we know where that value will be set as most developers familiar with the standard Makefile would check the value set here


# CHANNELS define the bundle channels used in the bundle.
# Add a new line here if you would like to change its default config. (E.g CHANNELS = "candidate,fast,stable")
Expand All @@ -31,8 +28,8 @@ BUNDLE_METADATA_OPTS ?= $(BUNDLE_CHANNELS) $(BUNDLE_DEFAULT_CHANNEL)
# This variable is used to construct full image tags for bundle and catalog images.
#
# For example, running 'make bundle-build bundle-push catalog-build catalog-push' will build and push both
# ansible.com/eda-server-operator-bundle:$VERSION and ansible.com/eda-server-operator-catalog:$VERSION.
IMAGE_TAG_BASE ?= quay.io/ansible/eda-server-operator
# example.com/temp-operator-bundle:$VERSION and example.com/temp-operator-catalog:$VERSION.
# IMAGE_TAG_BASE ?= quay.io/<org>/<operator-name> # Set in operator.mk
Comment on lines +31 to +32
Copy link
Copy Markdown
Member

@AlexSCorey AlexSCorey Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need to keep this in?

Copy link
Copy Markdown
Member Author

@lucas-benedito lucas-benedito Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For now, I will keep it. The next Makefile update that we do (it will happen on all operators) then I can drop the commented out value from the operator-sdk sourced Makefile.
I only kept to ensure we know where that value will be set as most developers familiar with the standard Makefile would check the value set here


# BUNDLE_IMG defines the image:tag used for the bundle.
# You can use it as an arg. (E.g make bundle-build BUNDLE_IMG=<some-registry>/<project-name-bundle>:<tag>)
Expand All @@ -49,6 +46,11 @@ ifeq ($(USE_IMAGE_DIGESTS), true)
BUNDLE_GEN_FLAGS += --use-image-digests
endif

# Set the Operator SDK version to use. By default, what is installed on the system is used.
# This is useful for CI or a project to utilize a specific version of the operator-sdk toolkit.
OPERATOR_SDK_VERSION ?= v1.40.0
CONTAINER_TOOL ?= podman

# Image URL to use all building/pushing image targets
IMG ?= $(IMAGE_TAG_BASE):$(VERSION)

Expand Down Expand Up @@ -81,51 +83,50 @@ run: ansible-operator ## Run against the configured Kubernetes cluster in ~/.kub

.PHONY: docker-build
docker-build: ## Build docker image with the manager.
$(ENGINE) build $(BUILD_ARGS) -t ${IMG} .
docker build $(BUILD_ARGS) -t ${IMG} .

.PHONY: docker-push
docker-push: ## Push docker image with the manager.
$(ENGINE) push ${IMG}
docker push ${IMG}

# PLATFORMS defines the target platforms for the manager image be build to provide support to multiple
# architectures. (i.e. make docker-buildx IMG=myregistry/mypoperator:0.0.1). To use this option you need to:
# - able to use docker buildx . More info: https://docs.docker.com/build/buildx/
# - have enable BuildKit, More info: https://docs.docker.com/develop/develop-images/build_enhancements/
# - be able to push the image for your registry (i.e. if you do not inform a valid value via IMG=<myregistry/image:<tag>> than the export will fail)
# To properly provided solutions that supports more than one platform you should use this option.
PLATFORMS ?= linux/arm64,linux/amd64,linux/s390x,linux/ppc64le
.PHONY: docker-buildx
docker-buildx: ## Build and push docker image for the manager for cross-platform support
- docker buildx create --name project-v3-builder
docker buildx use project-v3-builder
- docker buildx build --push $(BUILD_ARGS) --platform=$(PLATFORMS) --tag ${IMG} -f Dockerfile .
- docker buildx rm project-v3-builder

.PHONY: podman-buildx
podman-buildx: ## Build and push podman image for the manager for cross-platform support
podman build --platform=$(PLATFORMS) $(BUILD_ARGS) --manifest ${IMG} -f Dockerfile .
podman manifest push --all ${IMG} ${IMG}

##@ Deployment

ifndef ignore-not-found
ignore-not-found = false
endif

.PHONY: install
install: kustomize ## Install CRDs into the K8s cluster specified in ~/.kube/config.
$(KUSTOMIZE) build config/crd | kubectl apply -f -

.PHONY: uninstall
uninstall: kustomize ## Uninstall CRDs from the K8s cluster specified in ~/.kube/config.
$(KUSTOMIZE) build config/crd | kubectl delete -f -
$(KUSTOMIZE) build config/crd | kubectl delete --ignore-not-found=$(ignore-not-found) -f -

.PHONY: deploy
deploy: kustomize ## Deploy controller to the K8s cluster specified in ~/.kube/config.
cd config/manager && $(KUSTOMIZE) edit set image controller=${IMG}
cd config/default && $(KUSTOMIZE) edit set namespace ${NAMESPACE}
$(KUSTOMIZE) build config/default | kubectl apply -f -

.PHONY: undeploy
undeploy: ## Undeploy controller from the K8s cluster specified in ~/.kube/config.
cd config/default && $(KUSTOMIZE) edit set namespace ${NAMESPACE}
$(KUSTOMIZE) build config/default | kubectl delete -f -
$(KUSTOMIZE) build config/default | kubectl delete --ignore-not-found=$(ignore-not-found) -f -

## Location for locally installed tools
LOCALBIN ?= $(shell pwd)/bin

OS := $(shell uname -s | tr '[:upper:]' '[:lower:]')
ARCH := $(shell uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/')
Expand All @@ -138,30 +139,14 @@ ifeq (,$(shell which kustomize 2>/dev/null))
@{ \
set -e ;\
mkdir -p $(dir $(KUSTOMIZE)) ;\
curl -sSLo - https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize/v5.3.0/kustomize_v5.3.0_$(OS)_$(ARCH).tar.gz | \
curl -sSLo - https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize/v5.6.0/kustomize_v5.6.0_$(OS)_$(ARCH).tar.gz | \
tar xzf - -C bin/ ;\
}
else
KUSTOMIZE = $(shell which kustomize)
endif
endif

.PHONY: operator-sdk
OPERATOR_SDK = $(shell pwd)/bin/operator-sdk
operator-sdk: ## Download operator-sdk locally if necessary, preferring the $(pwd)/bin path over global if both exist.
ifeq (,$(wildcard $(OPERATOR_SDK)))
ifeq (,$(shell which operator-sdk 2>/dev/null))
@{ \
set -e ;\
mkdir -p $(dir $(OPERATOR_SDK)) ;\
curl -sSLo $(OPERATOR_SDK) https://github.com/operator-framework/operator-sdk/releases/download/v1.40.0/operator-sdk_$(OS)_$(ARCH) ;\
chmod +x $(OPERATOR_SDK) ;\
}
else
OPERATOR_SDK = $(shell which operator-sdk)
endif
endif

.PHONY: ansible-operator
ANSIBLE_OPERATOR = $(shell pwd)/bin/ansible-operator
ansible-operator: ## Download ansible-operator locally if necessary, preferring the $(pwd)/bin path over global if both exist.
Expand All @@ -170,31 +155,48 @@ ifeq (,$(shell which ansible-operator 2>/dev/null))
@{ \
set -e ;\
mkdir -p $(dir $(ANSIBLE_OPERATOR)) ;\
curl -sSLo $(ANSIBLE_OPERATOR) https://github.com/operator-framework/operator-sdk/releases/download/v1.40.0/ansible-operator_$(OS)_$(ARCH) ;\
curl -sSLo $(ANSIBLE_OPERATOR) https://github.com/operator-framework/ansible-operator-plugins/releases/download/$(OPERATOR_SDK_VERSION)/ansible-operator_$(OS)_$(ARCH) ;\
chmod +x $(ANSIBLE_OPERATOR) ;\
}
else
ANSIBLE_OPERATOR = $(shell which ansible-operator)
endif
endif

.PHONY: operator-sdk
OPERATOR_SDK ?= $(LOCALBIN)/operator-sdk
operator-sdk: ## Download operator-sdk locally if necessary.
ifeq (,$(wildcard $(OPERATOR_SDK)))
ifeq (, $(shell which operator-sdk 2>/dev/null))
@{ \
set -e ;\
mkdir -p $(dir $(OPERATOR_SDK)) ;\
curl -sSLo $(OPERATOR_SDK) https://github.com/operator-framework/operator-sdk/releases/download/$(OPERATOR_SDK_VERSION)/operator-sdk_$(OS)_$(ARCH) ;\
chmod +x $(OPERATOR_SDK) ;\
}
else
OPERATOR_SDK = $(shell which operator-sdk)
endif
endif


.PHONY: bundle
bundle: kustomize operator-sdk ## Generate bundle manifests and metadata, then validate generated files.
$(OPERATOR_SDK) generate kustomize manifests -q
cd config/manager && $(KUSTOMIZE) edit set image controller=$(IMG)
$(KUSTOMIZE) build config/manifests | $(OPERATOR_SDK) generate bundle -q --overwrite --version $(VERSION) $(BUNDLE_METADATA_OPTS)
$(KUSTOMIZE) build config/manifests | $(OPERATOR_SDK) generate bundle $(BUNDLE_GEN_FLAGS)
$(OPERATOR_SDK) bundle validate ./bundle

.PHONY: bundle-build
bundle-build: ## Build the bundle image.
$(ENGINE) build -f bundle.Dockerfile -t $(BUNDLE_IMG) .
$(CONTAINER_TOOL) build -f bundle.Dockerfile -t $(BUNDLE_IMG) .

.PHONY: bundle-push
bundle-push: ## Push the bundle image.
$(MAKE) docker-push IMG=$(BUNDLE_IMG)

.PHONY: opm
OPM = ./bin/opm
OPM = $(LOCALBIN)/opm
opm: ## Download opm locally if necessary.
ifeq (,$(wildcard $(OPM)))
ifeq (,$(shell which opm 2>/dev/null))
Expand Down Expand Up @@ -226,17 +228,15 @@ endif
# https://github.com/operator-framework/community-operators/blob/7f1438c/docs/packaging-operator.md#updating-your-existing-operator
.PHONY: catalog-build
catalog-build: opm ## Build a catalog image.
$(OPM) index add --container-tool $(ENGINE) --mode semver --tag $(CATALOG_IMG) --bundles $(BUNDLE_IMGS) $(FROM_INDEX_OPT)
$(OPM) index add --container-tool $(CONTAINER_TOOL) --mode semver --tag $(CATALOG_IMG) --bundles $(BUNDLE_IMGS) $(FROM_INDEX_OPT)

# Push the catalog image.
.PHONY: catalog-push
catalog-push: ## Push a catalog image.
$(MAKE) docker-push IMG=$(CATALOG_IMG)

# Generate operator.yaml with image tag as a release artifact
.PHONY: generate-operator-yaml
generate-operator-yaml: kustomize ## Generate operator.yaml with image tag $(VERSION)
@cd config/manager && $(KUSTOMIZE) edit set image controller=quay.io/ansible/eda-server-operator:${VERSION}
@$(KUSTOMIZE) build config/default > ./operator.yaml

@echo "Generated operator.yaml with image tag $(VERSION)"
##@ Includes
# Operator-specific targets and variables
-include makefiles/operator.mk
# Shared dev workflow targets (synced across all operator repos)
-include makefiles/common.mk
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ Table of Contents

## Contributing

Please visit [our contributing guide](./CONTRIBUTING.md) which has details about how to set up your development environment.
Please visit our [contributing guidelines](./CONTRIBUTING.md) and [development guide](./docs/development.md) for information on how to set up your environment, build and deploy the operator, and submit changes.

### Prerequisites

Expand Down
2 changes: 1 addition & 1 deletion config/default/kustomization.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Adds namespace to all resources.
namespace: eda-server-operator-system
namespace: eda

# Value of this field is prepended to the
# names of all resources, e.g. a deployment named
Expand Down
4 changes: 2 additions & 2 deletions dev/eda-cr/eda-openshift-cr.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ kind: EDA
metadata:
name: eda
spec:
automation_server_url: https://awx-awx.apps.aap-dev.ocp4.testing.ansible.com
automation_server_url: https://awx.example.com
automation_server_ssl_verify: 'no'
service_type: ClusterIP
ingress_type: Route
Expand Down Expand Up @@ -34,7 +34,7 @@ spec:
value: "Always"

# CA Bundle
bundle_cacert_secret: my-custom-certs
# bundle_cacert_secret: my-custom-certs
Copy link
Copy Markdown
Member

@AlexSCorey AlexSCorey Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we remove this?

Copy link
Copy Markdown
Member Author

@lucas-benedito lucas-benedito Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We've been keeping some of these parameters commented out in the example dev cr, as a new user can easily apply the parameter if they need it. We only do that for more commonly used parameters.
I would probably keep the commented out value here just for future reference.


# -- Resource Requirements
api:
Expand Down
Loading
Loading