Prepare for GitOps

GitOps uses a Git repository as the source of truth for the Ingress Controller installation and its routing resources. Instead of running an installation command and maintaining the resulting objects manually, you declare the desired state in Git. A GitOps controller continuously reconciles changes committed to the repository, detects differences in the cluster, and restores the declared state when drift occurs. This pull-based workflow makes changes reviewable, repeatable across environments, and recoverable from Git history.

The Git repository can contain the controller chart configuration, CRD ownership settings, credential references, and resources such as GatewayProxy, Gateway, and HTTPRoute. GitOps tools such as Argo CD and Flux reconcile these Kubernetes resources. The Ingress Controller watches the routing resources, translates them, and synchronizes the resulting gateway configuration.

GitOps manages the Kubernetes layer; the Ingress Controller remains responsible for translating routing resources and synchronizing gateway configuration.

Before installing the Ingress Controller with Argo CD or Flux, prepare the repository structure, resource and CRD ownership, and controller credentials. When you finish, continue to the appropriate procedure under Next Steps.

Prerequisites

Before you begin, ensure that you have:

• A Git repository that the GitOps controller can read.
• Permission to create the namespace, RBAC resources, admission webhook configuration, and CRDs used by the Ingress Controller.
• A secret-management solution that creates Secrets in the destination cluster without storing plaintext credentials or private keys in Git.
• An APISIX gateway and Admin API Service, or access to API7 Dashboard with permission to create an Ingress Controller gateway group.
• Network connectivity from the controller pods to the APISIX Admin API or API7 control plane.

Organize the Repository

Keep cluster infrastructure separate from application routing resources. The following example groups each cluster's controller and shared gateway resources under platform-owned infrastructure while leaving application routes with their application teams:

clusters/
  production/
    infrastructure/
      ingress-controller/
      gateway-resources/
    applications/
      payments/

Store the Argo CD Application or Flux HelmRepository and HelmRelease manifests in infrastructure/ingress-controller/. If you share configuration across clusters, keep reusable bases or components in a separate top-level directory and reference them from each cluster. Adapt the directory names and repository boundaries to your platform's ownership model.

Keep ordinary chart values in Git. Supply sensitive values through an existing Secret, an encrypted-secret controller, or an external secret store. Pin chart versions and remote manifest revisions; do not reference a moving branch for cluster-scoped CRDs.

Choose How to Store Kubernetes Resources

The workflows in this documentation use the official Helm chart for the Ingress Controller installation. Argo CD renders that chart and reconciles its output. Flux Helm Controller installs and upgrades it through a HelmRelease.

The Gateway and application resources have a separate lifecycle. Choose their source format based on how your platform already manages Kubernetes applications:

Source format	Use it when	GitOps integration
Plain Kubernetes YAML	Each environment has an independent set of resources or needs little customization.	Point an Argo CD Application or Flux Kustomization at the manifest directory. This is the default path in the tool-specific guides.
Kustomize bases and overlays	Several environments share most resources and require a small set of explicit differences.	Point Argo CD or Flux at the selected overlay.
Application Helm chart	The application already packages its Deployment, Service, and routing resources in a chart or needs extensive value-driven configuration.	Reconcile that chart with a separate Argo CD Application or Flux HelmRelease. Keep it separate from the controller release.

These formats produce Kubernetes resources that the Ingress Controller watches. Choosing one does not change how the controller translates and synchronizes those resources.

Plan Resource Ownership

Assign one reconciler to each object. Do not have Argo CD, Flux, a separate Helm release, and manual kubectl apply operations manage the same resource.

Resource	Recommended owner	Considerations
Ingress Controller namespace	Platform GitOps configuration	Any externally managed webhook or credential Secrets must exist before the resources that reference them are reconciled.
Gateway API CRDs	Cluster platform team	The charts include the Gateway API experimental channel. Do not overwrite a platform-managed bundle.
APISIX CRDs	Cluster platform team or controller release	Keep the owner consistent across upgrades.
Controller Deployment, Service, RBAC, ConfigMap, and webhook	Controller release managed by the selected GitOps tool	Do not manage these resources with a separate Helm release or manual commands.
APISIX or API7 gateway	Separate infrastructure release	Keep the gateway lifecycle independent from the controller when possible.
GatewayProxy, GatewayClass, and Gateway	Platform configuration repository	Reconcile these after their CRDs and the controller are ready. If the chart creates a default GatewayProxy, leave it under chart ownership.
IngressClass	Controller release for APISIX; platform configuration for API7	The APISIX chart renders its configured IngressClass. Do not duplicate it elsewhere.
Routes, Services, and policies	Application team repository	Separate application delivery from cluster infrastructure.
Admin keys and TLS private keys	Destination-cluster secret controller	Commit only Secret references or encrypted secret resources.

Choose CRD Ownership

The APISIX and API7 controller charts used in these guides each package two CRD bundles: the APISIX Ingress Controller CRDs and the Gateway API v1.3.0 experimental-channel CRDs. The chart-level CRD settings apply to both bundles; they cannot install or skip only one of them. Choose the ownership model before installing the controller.

Gateway API recommends that cluster administrators manage Gateway API CRDs, especially when another controller or the Kubernetes platform already provides them. For more information, see Gateway API CRD management.

Let the Controller Release Own CRDs

Use this model only when neither CRD bundle is already managed by the platform or another release. The controller release creates both bundles. Follow the tool-specific procedure to configure their upgrade and deletion behavior, and review CRD changes separately during every controller upgrade.

Let the Platform Own CRDs

Use this model when Gateway API CRDs are already managed by the platform, several controllers share them, or the controller release should not manage cluster-scoped resources. Because the chart cannot skip the Gateway API CRDs independently, the platform must manage both the Gateway API and APISIX CRD bundles.

1. Reconcile the required Gateway API and APISIX CRDs from a separate, pinned cluster-infrastructure source.
2. Wait until every CRD reports an Established condition.
3. Configure the controller release to skip its bundled CRDs.
4. Ensure that the controller release does not delete or replace the platform-owned CRDs.

This model lets the platform upgrade CRDs independently and prevents a controller rollback from replacing their schemas. Verify that the installed CRD versions remain compatible with this version of the Ingress Controller. The Argo CD and Flux procedures explain how to implement the selected ownership model with each tool.

Prepare the Gateway Connection

A GatewayProxy defines how the Ingress Controller connects and authenticates to the APISIX Admin API or API7 control plane. When it references a Kubernetes Secret, the controller reads that Secret from the GatewayProxy namespace. Configure your secret-management solution to create the Secret before applying the GatewayProxy so that the initial reconciliation can succeed.

APISIX

Create a Secret named apisix-admin-key with an admin-key key through your secret-management solution. Reference it in the chart values:

values.yaml

config:
  provider:
    type: apisix-standalone
gatewayProxy:
  createDefault: true
  provider:
    type: ControlPlane
    controlPlane:
      service:
        name: apisix-admin
        port: 9180
      auth:
        type: AdminKey
        adminKey:
          valueFrom:
            secretKeyRef:
              name: apisix-admin-key
              key: admin-key

This example follows the API-driven standalone installation in Set Up APISIX Ingress Controller. The chart values configure the controller for standalone mode and create a default GatewayProxy that targets the APISIX Admin API Service in the controller namespace.

When APISIX is managed separately, ensure that its Admin API accepts connections from the controller pods. Configure deployment.admin.allow_admin in the APISIX config.yaml; if APISIX is installed with Helm, use apisix.admin.allow.ipList to render that setting. Restrict access to the required pod or cluster CIDR.

API7

1. Create an Ingress Controller gateway group in API7 Dashboard.
2. In the deployment steps, select Gateway API, then generate the controller and GatewayProxy deployment steps.
3. Copy the generated non-sensitive chart values and the GatewayProxy, GatewayClass, and Gateway manifests into the GitOps repository.
4. Keep the generated valueFrom.secretKeyRef in the GatewayProxy and have your secret-management solution create the referenced Secret and key in the destination cluster.
5. If you change the generated Secret name or key, update the GatewayProxy reference to match.

If you use Ingress or APISIX custom resources instead of Gateway API resources, select the corresponding Ingress tab in API7 Dashboard. Reconcile its generated IngressClass in place of the GatewayClass and Gateway.

Do not commit the generated deployment script or its Secret manifest as generated. The script embeds the gateway-group admin key in the Secret's stringData.

Next Steps

After completing these preparation steps, continue with the guide for the GitOps tool that will manage the Ingress Controller:

• Follow Manage with Argo CD when Argo CD or Red Hat OpenShift GitOps owns the controller resources.
• Follow Manage with Flux when Flux Helm Controller owns the Helm release.