Skip to content

Commit 2e1f531

Browse files
NimRegevNimRegev
committed
Add content for side-by-side install
Added prereqs and updated step-by-step for side-by-side
1 parent 2e43415 commit 2e1f531

File tree

1 file changed

+153
-77
lines changed

1 file changed

+153
-77
lines changed

‎_docs/installation/gitops/hybrid-gitops-helm-installation.md

Lines changed: 153 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -7,25 +7,153 @@ redirect_from:
77
toc: true
88
---
99

10-
Install the Hybrid Runtime for GitOps through a Helm chart.
11-
10+
Install the Hybrid Runtime for GitOps through a Helm chart.
1211
>**ATTENTION**:
1312
We have transitioned to a Helm-based installation for Hybrid GitOps Runtimes for improved experience and performance.
1413
The [CLI-based installation for Hybrid GitOps]({{site.baseurl}}/docs/installation/gitops/hybrid-gitops/) is now considered legacy.
1514
We will deprecate this installation mode permanently in the coming months. Please stay tuned for further updates and instructions, including the migration process.
1615

16+
Hybrid GitOps Runtime offers two installation options via Helm, each catering to specific use cases:
17+
18+
* **Side-by-Side installation: Native Argo CD and GitOps**
19+
This installation option combines Argo CD and GitOps Runtime in a side-by-side setup, suitable for environments where you already have Argo CD installed on your cluster, and want to extend it with GitOps capabilities.
20+
Side-by-Side GitOps installation provides seamless integration of both Native Argo CD and GitOps Runtime features in a single cluster.
21+
22+
* **Dedicated GitOps installation**
23+
This installation option is solely on GitOps Runtime .
24+
Suitable for environments where you want to deploy GitOps Runtime on your cluster without any pre-existing Argo CD installation.
25+
Dedicated GitOps installation also installs the Argo project components but as .
26+
1727

18-
If you already have a Codefresh acccount, go for the [quick Helm install](#quick-helm-install-for-hybrid-gitops-runtime).
28+
Choose the installation option that best aligns with your specific requirements and current environment setup. Whichever option you choose, review the table listing the prerequisites for each installation method, and then follow the detailed instructions as needed.
29+
30+
If you already have a Codefresh acccount, go for the [quick Helm install](#quick-helm-install-for-hybrid-gitops-runtime), or installation via [Terraform](/#using-terraform-for-installation).
1931

2032
For step-by-step installation from the Codefresh UI, see [Step-by-step Hybrid GitOps Runtime installation](#step-by-step-hybrid-gitops-runtime-installation).
2133

22-
>Hybrid GitOps installation with Helm is currently in Beta.
34+
## Preparing for Hybrid GitOps installation
35+
36+
37+
| Prerequisite | Side-by-Side | Dedicated |
38+
|------------------------------------- |:------------:|:-------------:|
39+
| ArgoCD password<br>**WARNING**: Avoid changing the ArgoCD password using the `argocd-initial-admin-secret` via the ArgoCD UI. Doing so can cause system instability and disrupt the Codefresh platform. | ✅ | ✅ |
40+
| Argo project components<br>Dedicated GitOps requires a cluster without Argo project components, including Argo Rollouts, Argo CD, Argo Events, and Argo Workflows. | N/A | ✅ |
41+
| [Minor versions](#minor-versions)<br>Chart version must match the upstream version used by Codefresh. | ✅ | N/A |
42+
| [Argo project CRDs](#argo-project-crds)<br>Recommended that the GitOps Runtime Helm chart adopts and manages CRDs, either all the CRDs or only Argo Rollout CRDs. | ✅ | ✅ |
43+
| [Image overrides for private registries](#image-overrides-for-private-registries)<br>Override image values for subcharts and container images when using private registries. | ✅ | ✅ |
44+
| [Custom repository certificates](#custom-repository-certificates)<br>Authenticate on-premises Git servers using repository certificates. | ✅ | ✅ |
45+
| [fullnameOverride for resources](#side-by-side-fullnameoverride-for-resources)<br>Avoid conflicts when multiple instances of the same resources have the same name or attempt to control the same objects. | ✅ | N/A |
46+
| [`label` versus `annotation` for resource tracking](#side-by-side-label-versus-annotation-for-resource-tracking)<br>Use different methods to track native ArgoCD's and GitOps Runtime's ArgoCD resources. | ✅ | N/A |
47+
48+
49+
50+
### Side-by-Side: Minor versions
51+
For Side-by-Side installation, use the same upstream chart version of ArgoCD as Codefresh.
52+
53+
To get the Codefresh chart version of ArgoCD, check the `dependencies` section in the GitOps Runtime chart for <upstream chart version>-<codefresh-version id>.
54+
55+
### Argo project CRDs
56+
You can handle Argo project CRDs outside the chart, or as recommended, adopt the CRDs to be managed by the GitOps Runtime Helm release. Allowing the Runtime to manage the CRDs also ensures that the CRDs are automatically upgraded whenever the Runtime is upgraded.
57+
58+
If you already have Argo project CRDs on your cluster, you have two options:
59+
60+
#### Handle Argo project CRDs outside of the chart
61+
See [Argo's readme on Helm charts](https://github.com/argoproj/argo-helm/blob/main/README.md){:target="\_blank"}.
62+
63+
Disable CRD installation under the relevant section for each of the Argo projects in the Helm chart:<br>
64+
`--set <argo-project>.crds.install=false`<br>
65+
where:<br>
66+
`<argo-project>` is the argo project component: `argo-cd`, `argo-workflows`, `argo-rollouts` and `argo-events`.
67+
68+
#### Adopt the Argo project CRDs
69+
You can either adopt all CRDs which is the recommended option, or only Argo Rollout CRDs.
70+
71+
**Option 1: Adopt All CRDs (Recommended)**
72+
Adopting all CRDs switches ownership to the Hybrid GitOps Runtime, allowing them to be managed by the GitOps Runtime chart.
73+
74+
Run this script _before_ installation:
75+
```
76+
curl https://raw.githubusercontent.com/codefresh-io/gitops-runtime-helm/main/scripts/adopt-crds.sh | bash -s <runtime-helm-release name> <runtime-namespace>
77+
```
78+
79+
**Option 2: Adopt only Argo Rollout CRDs**
80+
You can also adopt only those CRDs that apply to Argo Rollouts.
81+
82+
We highly recommend allowing the GitOps Runtime to control manage the CRDs as there should be only one active Argo Rollouts controller active on the Runtime cluster.
83+
```
84+
#!/bin/sh
85+
RELEASE=<runtime-helm-release-name>
86+
NAMESPACE=<runtime-namespace>
87+
kubectl label --overwrite crds $(kubectl get crd | grep argoproj.io | awk '{print $1}' | xargs) app.kubernetes.io/managed-by=Helm
88+
kubectl annotate --overwrite crds $(kubectl get crd | grep argoproj.io | awk '{print $1}' | xargs) meta.helm.sh/release-name=$RELEASE
89+
kubectl annotate --overwrite crds $(kubectl get crd | grep argoproj.io | awk '{print $1}' | xargs) meta.helm.sh/release-namespace=$NAMESPACE
90+
```
91+
### Side-by-Side: `fullnameOverride` for resources
92+
Side-by-Side GitOps installation can cause conflicts when multiple instances of the same resources have the same name or attempt to control the same objects.
93+
94+
As with the CRDs, you can avoid resource conflicts at the cluster level for all Argo CD resources or only for Argo Rollouts resources.
95+
96+
**Option 1: `fullnameOverride` for argo-cd**<br>
97+
Set the value for `argo-cd.fullnameOverride` in the Helm chart to `codefresh-argo-cd`.
98+
99+
```
100+
argo-cd:
101+
fullnameOverride: codefresh-argo-cd
102+
```
103+
104+
**Option 2: `fullnameOverride` for argo-rollouts**
105+
Set the value for `argo-rollouts.fullnameOverride` in the Helm chart to `codefresh-argo-rollouts`.
106+
107+
```
108+
argo-rollouts:
109+
fullnameOverride: codefresh-argo-rollouts
110+
```
111+
### Side-by-Side: `label` versus `annotation` for resource tracking
112+
113+
For Side-by-Side installations, native ArgoCD and the GitOps Runtime's ArgoCD must use different methods to track resources.
114+
Using the same tracking method can result in conflicts when using the same application names or when tracking the same resource in both ArgoCD instances.
23115

24-
## ArgoCD password
25116

26-
>**WARNING**:
27-
Do not change the ArgoCD password by logging into the ArgoCD UI with the `argocd-initial-admin-secret`.
28-
Changing the ArgoCD password can result in system instability, and disrupt the proper functioning of the Codefresh platform.
117+
**Verify/set resource tracking method for native ArgoCD**
118+
In the `argocd-cm ConfigMap` within the ArgoCD namespace, verify that the `application.resourceTrackingMethod` either doesn't exist, meaning that it uses the default which is `label`, or is explicitly set to `label`.
119+
120+
**Set resource tracking method for GitOps Runtime's ArgoCD**
121+
In the Runtime's Helm chart, set `argo-cd.configs.cm.application.resourceTrackingMethod` to `annotation`.
122+
```
123+
argo-cd:
124+
configs:
125+
cm:
126+
application.resourceTrackingMethod: annotation #annotation+label is also valid
127+
```
128+
### Image overrides for private registries
129+
If you use private registries, you must override specific image values for the different subcharts and container images.
130+
We have a utility to help override image values for GitOps Runtimes, which creates values files that match the structure of the subcharts, allowing you to easily replace image registries. During chart installation, you can provide these values files to override the images, as needed.
131+
For more details, see [ArtifactHub](https://artifacthub.io/packages/helm/codefresh-gitops-runtime/gitops-runtime#using-with-private-registries---helper-utility){:target="\_blank"}.
132+
133+
### Custom repository certificates
134+
135+
On-premises Git servers require repository certificates to authenticate users.
136+
137+
If your Git servers are on-premises, add the repository certificates to your Codefresh `values` file, in `.values.argo-cd`. These values are used by the GitOps Runtime's ArgoCD.
138+
For details on adding repository certificates, see this [section](https://github.com/codefresh-io/argo-helm/blob/argo-cd-5.29.2-cap-CR-18430/charts/argo-cd/values.yaml#LL336C7-L336C7){:target="\_blank"}.
139+
140+
{% highlight yaml %}
141+
global:
142+
codefresh:
143+
tls:
144+
caCerts:
145+
# optional - use an existing secret that contains the cert
146+
# secretKeyRef:
147+
# name: my-certificate-secret
148+
# key: ca-bundle.crt
149+
# or create "codefresh-tls-certs" secret
150+
secret:
151+
create: true
152+
content: |
153+
-----BEGIN CERTIFICATE-----
154+
...
155+
-----END CERTIFICATE-----
156+
{% endhighlight yaml %}
29157

30158
## Quick Helm install for Hybrid GitOps Runtime
31159

@@ -82,39 +210,13 @@ where:
82210

83211

84212

85-
## Argo project components & CRDs
86-
Hybrid GitOps installation requires a cluster without Argo project components and CRDs.
87-
88-
Argo project components include Argo Rollouts, Argo CD, Argo Events, and Argo Workflows.
89-
90-
You can handle Argo project CRDs outside the chart, or as recommended, adopt the CRDs to be managed by the GitOps Runtime Helm release.
91-
92-
If you already have Argo project CRDs on your cluster, do one of the following:
93-
* Handle Argo projects CRDs outside of the chart (see [Argo's readme on Helm charts](https://github.com/argoproj/argo-helm/blob/main/README.md){:target="\_blank"})
94-
Disable CRD installation under the relevant section for each of the Argo projects in the Helm chart:<br>
95-
`--set <argo-project>.crds.install=false`<br>
96-
where:<br>
97-
`<argo-project>` is the argo project component: `argo-cd`, `argo-workflows`, `argo-rollouts` and `argo-events`.
98213

99-
* Adopt the CRDs<br>
100-
Adopting the CRDs allows them to be managed by the `gitops-runtime helm release`. Doing so ensures when you upgrade the Hybrid GitOps Runtime, the CRDs are also automatically upgraded.
101-
102-
Run this script _before_ installation:
103-
104-
```
105-
#!/bin/sh
106-
RELEASE=<helm-release-name>
107-
NAMESPACE=<target-namespace>
108-
kubectl label --overwrite crds $(kubectl get crd | grep argoproj.io | awk '{print $1}' | xargs) app.kubernetes.io/managed-by=Helm
109-
kubectl annotate --overwrite crds $(kubectl get crd | grep argoproj.io | awk '{print $1}' | xargs) meta.helm.sh/release-name=$RELEASE
110-
kubectl annotate --overwrite crds $(kubectl get crd | grep argoproj.io | awk '{print $1}' | xargs) meta.helm.sh/release-namespace=$NAMESPACE
111-
```
112214

113215
## Using Terraform for installation
114216

115-
You can also use Terraform to install a Codefresh runtime with the [Helm provider](https://registry.terraform.io/providers/hashicorp/helm/latest/docs){:target="\_blank"}.
217+
You can also use Terraform to install a Hybrid GitOps Runtime with the [Helm provider](https://registry.terraform.io/providers/hashicorp/helm/latest/docs){:target="\_blank"}.
116218

117-
Here is an example
219+
Here is an example:
118220

119221
```hcl
120222
resource "helm_release" "my_gitops_runtime" {
@@ -141,42 +243,10 @@ resource "helm_release" "my_gitops_runtime" {
141243
}
142244
```
143245

144-
Feel free to user a different chart version and your own runtime name. You can get both values for Codefresh token and account ID from the Codefresh UI as explained in the previous section.
145-
146-
By default the Codefresh runtime can deploy to the cluster it is installed on.
147-
You can also [use Terraform to connect additional]({{site.baseurl}}/docs/installation/gitops/managed-cluster/#add-a-managed-cluster-with-terraform) external clusters to your runtime.
148-
246+
Feel free to user a different chart version and a custom name for the Hybrid GitOps Runtime. You can get values for both the Codefresh API token and account ID from the Codefresh UI as explained in the previous section.
149247

150-
151-
152-
## Image overrides for private registries
153-
If you use private registries, you need to override specific image values for the different subcharts and container images.
154-
We have a utility to help override image values for GitOps Runtimes. The utility creates values files that match the structure of the subcharts, allowing you to easily replace image registries. During chart installation, you can provide these values files to override the images, as needed.
155-
For more details, see [ArtifactHub](https://artifacthub.io/packages/helm/codefresh-gitops-runtime/gitops-runtime#using-with-private-registries---helper-utility){:target="\_blank"}.
156-
157-
## Custom repository certificates
158-
159-
Repository certificates are required to authenticate users to on-premises Git servers.
160-
161-
If your Git servers are on-premises, add the repository certificates to your Codefresh `values` file, in `.values.argo-cd`. These values are used by the argo-cd Codefresh deploys. For details on adding repository certificates, see this [section](https://github.com/codefresh-io/argo-helm/blob/argo-cd-5.29.2-cap-CR-18430/charts/argo-cd/values.yaml#LL336C7-L336C7){:target="\_blank"}.
162-
163-
{% highlight yaml %}
164-
global:
165-
codefresh:
166-
tls:
167-
caCerts:
168-
# optional - use an existing secret that contains the cert
169-
# secretKeyRef:
170-
# name: my-certificate-secret
171-
# key: ca-bundle.crt
172-
# or create "codefresh-tls-certs" secret
173-
secret:
174-
create: true
175-
content: |
176-
-----BEGIN CERTIFICATE-----
177-
...
178-
-----END CERTIFICATE-----
179-
{% endhighlight yaml %}
248+
By default, the GitOps Runtime can deploy to the cluster it is installed on.
249+
You can also [use Terraform to connect additional]({{site.baseurl}}/docs/installation/gitops/managed-cluster/#add-a-managed-cluster-with-terraform) external clusters to your Runtime.
180250

181251

182252
## Step-by-step Hybrid GitOps Runtime installation
@@ -190,8 +260,8 @@ The Codefresh `values.yaml` is located [here](https://github.com/codefresh-io/gi
190260
* [Runtime token with the required scopes]({{site.baseurl}}/docs/reference/git-tokens/#git-runtime-token-scopes) which you need to supply as part of the Helm install command
191261
* [Personal Access Token (PAT)]({{site.baseurl}}/docs/reference/git-tokens/#git-personal-tokens) with the required scopes for Git-based actions
192262
* Server URLs for on-premises Git providers
193-
* Verify there are no Argo project components and CRDs in the target namespace or that you have adopted the CRDs (see [Argo project components & CRDs](#argo-project-components--crds))
194-
* For ingress-based runtimes only, verify that these ingress controllers are configured correctly:
263+
* Depending on the installation method, verify that you meet the relevant [prerequisites](#preparing-for-hybrid-gitops-installation)
264+
* For ingress-based GitOps Runtimes only, verify that these ingress controllers are configured correctly:
195265
* [Ambassador ingress configuration](#ambassador-ingress-configuration)
196266
* [AWS ALB ingress configuration](#aws-alb-ingress-configuration)
197267
* [Istio ingress configuration](#istio-ingress-configuration)
@@ -483,12 +553,19 @@ You cannot configure the Runtime as an Argo Application if you have not configur
483553
Create a [Git Source]({{site.baseurl}}/docs/installation/gitops/git-sources/#create-a-git-source) for the Runtime.
484554

485555
1. Optional. Create a Git Source.
486-
1. Continue with [Step 8: (Optional) Configure ingress-controllers](#step-8-optional-configure-ingress-controllers).
556+
1. Continue with [Step 8: Side-by-side: Remove Rollouts controller deployment](#step-8-side-by-side-remove-rollouts-controller-deployment).
487557

488-
### Step 8: (Optional) Configure ingress-controllers
558+
### Step 8: Side-by-side: Remove Rollouts controller deployment
559+
After confirming successful installation, remove the duplicate Argo Rollouts controller deployment to avoid having two controllers in the cluster.
560+
561+
>**IMPORTANT**:
562+
Make sure to remove only the `deployment` and not the CRDs. Removing the CRDs also removes Rollout objects and cause downtime for workloads.
563+
1. Continue with [Step 9: (Optional) Configure ingress-controllers](#step-9-optional-configure-ingress-controllers).
564+
565+
### Step 9: (Optional) Configure ingress-controllers
489566
Required only for ALB AWS, Istio, or NGINX Enterprise ingress-controllers.<br>
490567

491-
* Complete configuring these ingress controllers:
568+
1. Complete configuring these ingress controllers:
492569
* [ALB AWS: Alias DNS record in route53 to load balancer](#create-an-alias-to-load-balancer-in-route53)
493570
* [Istio: Configure cluster routing service](#cluster-routing-service)
494571
* [NGINX Enterprise ingress controller: Patch certificate secret](#patch-certificate-secret)
@@ -498,7 +575,6 @@ That's it! You have successfully completed installing a Hybrid GitOps Runtime wi
498575
You can now add [external clusters to the Runtime]({{site.baseurl}}/docs/installation/gitops/managed-cluster/), and [create and deploy GitOps applications]({{site.baseurl}}/docs/deployments/gitops/create-application/).
499576

500577

501-
502578
## Minimum system requirements
503579

504580
{: .table .table-bordered .table-hover}

0 commit comments

Comments
 (0)