Note: Maintenance support for Kubernetes v1.19 ended on Oct 28, 2021.{:/}| +|Operating systems|{::nomarkdown}
- Windows 10/7
- Linux
- OSX {:/}| +|Node requirements| {::nomarkdown}
- Memory: 5000 MB
- CPU: 2
- GitHub: SaaS and on-premises versions
- Bitbucket: SaaS and Bitbucket server (on-premises) 5.4.0 version and above
- GitLab: SaaS and on-premise versions (API v4 only)
- Single node: 8 CPU core and 16GB RAM
- Multi node: master(s) + 3 nodes with 4 CPU core and 8GB RAM (24 GB in total)
- GitHub
- Bitbucket Cloud
- Ambassador {:/}(see [Ambassador ingress configuration](#ambassador-ingress-configuration)){::nomarkdown}
- AWS ALB (Application Load Balancer) {:/} (see [AWS ALB ingress configuration](#aws-alb-ingress-configuration)){::nomarkdown}
- Istio {:/} (see [Istio ingress configuration](#istio-ingress-configuration)){::nomarkdown}
- NGINX Enterprise (nginx.org/ingress-controller) {:/} (see [NGINX Enterprise ingress configuration](#nginx-enterprise-ingress-configuration)){::nomarkdown}
- NGINX Community (k8s.io/ingress-nginx) {:/} (see [NGINX Community ingress configuration](#nginx-community-version-ingress-configuration)){::nomarkdown}
- Trafik {:/}(see [Traefik ingress configuration](#traefik-ingress-configuration))| +|Node requirements| {::nomarkdown}
- Memory: 5000 MB
- CPU: 2
- GitHub
- GitHub Enterprise
- GitLab Cloud
- GitLab Server
- Bitbucket Cloud
- Bitbucket Server
- Valid expiration date
- Scopes:
- GitHub and GitHub Enterprise: repo, admin-repo.hook
- GitLab Cloud and GitLab Server: api, read_repository
- Bitbucket Cloud and Server: Permissions: Read, Workspace membership: Read, Webhooks: Read and write, Repositories: Write, Admin
--api-url ` + `cf integration git register default --runtime --token ` + +{::nomarkdown} + +{:/} + +### Istio ingress configuration +For detailed configuration information, see [Istio ingress controller documentation](https://istio.io/latest/docs/tasks/traffic-management/ingress/kubernetes-ingress){:target="\_blank}. + +The table below lists the specific configuration requirements for Codefresh. + +{: .table .table-bordered .table-hover} +| What to configure | When to configure | +| -------------- | -------------- | +|Valid external IP address |_Before_ installing hybrid runtime | +|Valid TLS certificate| | +|TCP support | | +|Cluster routing service | _After_ installing hybrid runtime | + +{::nomarkdown} + +{:/} + +#### Valid external IP address +Run `kubectl get svc -A` to get a list of services and verify that the `EXTERNAL-IP` column for your ingress controller shows a valid hostname. + +{::nomarkdown} + +{:/} + +#### Valid TLS certificate +For secure runtime installation, the ingress controller must have a valid TLS certificate. +> Use the FQDN (Fully Qualified Domain Name) of the ingress controller for the TLS certificate. + +{::nomarkdown} + +{:/} + +#### TCP support +Configure the ingress controller to handle TCP requests. + +{::nomarkdown} + +{:/} + + + +#### Cluster routing service +> The cluster routing service must be configured _after_ installing the hybrid runtime. + +Based on the runtime version, you need to configure a single or multiple `VirtualService` resources for the `app-proxy`, `webhook`, and `workflow` services. + +##### Runtime version 0.0.543 or higher +Configure a single `VirtualService` resource to route traffic to the `app-proxy`, `webhook`, and `workflow` services, as in the example below. + +```yaml +apiVersion: networking.istio.io/v1alpha3 +kind: VirtualService +metadata: + namespace: pov-codefresh-istio-runtime # replace with your runtime name + name: internal-router +spec: + hosts: + - pov-codefresh-istio-runtime.sales-dev.codefresh.io # replace with your host name + gateways: + - istio-system/internal-router # replace with your gateway name + http: + - match: + - uri: + prefix: /webhooks + route: + - destination: + host: internal-router + port: + number: 80 + - match: + - uri: + prefix: /app-proxy + route: + - destination: + host: internal-router + port: + number: 80 + - match: + - uri: + prefix: /workflows + route: + - destination: + host: internal-router + port: + number: 80 +``` + +##### Runtime version 0.0.542 or lower + +Configure two different `VirtualService` resources, one to route traffic to the `app-proxy`, and the second to route traffic to the `webhook` services, as in the examples below. + +{::nomarkdown} + +{:/} + +**`VirtualService` example for `app-proxy`:** + +```yaml +apiVersion: networking.istio.io/v1alpha3 +kind: VirtualService +metadata: + namespace: test-runtime3 # replace with your runtime name + name: cap-app-proxy +spec: + hosts: + - my.support.cf-cd.com # replace with your host name + gateways: + - my-gateway # replace with your host name + http: + - match: + - uri: + prefix: /app-proxy + route: + - destination: + host: cap-app-proxy + port: + number: 3017 +``` + +**`VirtualService` example for `webhook`:** + +> Configure a `uri.prefix` and `destination.host` for each event-source if you have more than one. + +```yaml +apiVersion: networking.istio.io/v1alpha3 +kind: VirtualService +metadata: + namespace: test-runtime3 # replace with your runtime name + name: csdp-default-git-source +spec: + hosts: + - my.support.cf-cd.com # replace with your host name + gateways: + - my-gateway # replace with your gateway name + http: + - match: + - uri: + prefix: /webhooks/test-runtime3/push-github # replace `test-runtime3` with your runtime name, and `push-github` with the name of your event source + route: + - destination: + host: push-github-eventsource-svc # replace `push-github' with the name of your event source + port: + number: 80 + - match: + - uri: + prefix: /webhooks/test-runtime3/cypress-docker-images-push # replace `test-runtime3` with your runtime name, and `cypress-docker-images-push` with the name of your event source + route: + - destination: + host: cypress-docker-images-push-eventsource-svc # replace `cypress-docker-images-push` with the name of your event source + port: + number: 80 +``` + +{::nomarkdown} + +{:/} + +### NGINX Enterprise ingress configuration + +For detailed configuration information, see [NGINX ingress controller documentation](https://docs.nginx.com/nginx-ingress-controller){:target="\_blank}. + +The table below lists the specific configuration requirements for Codefresh. + +{: .table .table-bordered .table-hover} +| What to configure | When to configure | +| -------------- | -------------- | +|Verify valid external IP address |_Before_ installing hybrid runtime | +|Valid TLS certificate | | +|TCP support| | +|NGINX Ingress: Enable report status to cluster | | +|NGINX Ingress Operator: Enable report status to cluster| | +|Patch certificate secret |_After_ installing hybrid runtime + +{::nomarkdown} + +{:/} + +#### Valid external IP address +Run `kubectl get svc -A` to get a list of services and verify that the `EXTERNAL-IP` column for your ingress controller shows a valid hostname. + +{::nomarkdown} + +{:/} + +#### Valid TLS certificate +For secure runtime installation, the ingress controller must have a valid TLS certificate. +> Use the FQDN (Fully Qualified Domain Name) of the ingress controller for the TLS certificate. + +{::nomarkdown} + +{:/} + +#### TCP support +Configure the ingress controller to handle TCP requests. + +{::nomarkdown} + +{:/} + +#### NGINX Ingress: Enable report status to cluster + +If the ingress controller is not configured to report its status to the cluster, Argo’s health check reports the health status as “progressing” resulting in a timeout error during installation. + +* Pass `--report-ingress-status` to `deployment`. + +```yaml +spec: + containers: + - args: + - --report-ingress-status +``` + +{::nomarkdown} + +{:/} + +#### NGINX Ingress Operator: Enable report status to cluster + +If the ingress controller is not configured to report its status to the cluster, Argo’s health check reports the health status as “progressing” resulting in a timeout error during installation. + +1. Add this to the `Nginxingresscontrollers` resource file: + + ```yaml + ... + spec: + reportIngressStatus: + enable: true + ... + ``` + +1. Make sure you have a certificate secret in the same namespace as the runtime. Copy an existing secret if you don't have one. +You will need to add this to the `ingress-master` when you have completed runtime installation. + +{::nomarkdown} + +{:/} + +#### Patch certificate secret +> The certificate secret must be configured _after_ installing the hybrid runtime. + +Patch the certificate secret in `spec.tls` of the `ingress-master` resource. +The secret must be in the same namespace as the runtime. + +1. Go to the runtime namespace with the NGINX ingress controller. +1. In `ingress-master`, add to `spec.tls`: + + ```yaml + tls: + - hosts: + - + secretName: + ``` + +{::nomarkdown} + +{:/} + +### NGINX Community version ingress configuration + +Codefresh has been tested with and supports implementations of the major providers. For your convenience, we have provided configuration instructions, both for supported and untested providers in [Provider-specific configuration](#provider-specific-configuration). + + +This section lists the specific configuration requirements for Codefresh to be completed _before_ installing the hybrid runtime. +* Verify valid external IP address +* Valid TLS certificate +* TCP support + +{::nomarkdown} + +{:/} + +#### Valid external IP address +Run `kubectl get svc -A` to get a list of services, and verify that the `EXTERNAL-IP` column for your ingress controller shows a valid hostname. + +{::nomarkdown} + +{:/} + +#### Valid TLS certificate +For secure runtime installation, the ingress controller must have a valid TLS certificate. +> Use the FQDN (Fully Qualified Domain Name) of the ingress controller for the TLS certificate. + +{::nomarkdown} + +{:/} + +#### TCP support +Configure the ingress controller to handle TCP requests. + +Here's an example of TCP configuration for NGINX Community on AWS. +Verify that the `ingress-nginx-controller` service manifest has either of the following annotations: + +`service.beta.kubernetes.io/aws-load-balancer-backend-protocol: "tcp"` +OR +`service.beta.kubernetes.io/aws-load-balancer-type: nlb` + +{::nomarkdown} + +{:/} + +#### Provider-specific configuration + +> The instructions are valid for `k8s.io/ingress-nginx`, the community version of NGINX. + + ++AWS
+-
+
- Apply:
+ kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.1.1/deploy/static/provider/aws/deploy.yaml +
+ - Verify a valid external address exists:
+ kubectl get svc ingress-nginx-controller -n ingress-nginx +
+
++ +Azure (AKS)
+-
+
- Apply:
+ kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.1.1/deploy/static/provider/cloud/deploy.yaml +
+ - Verify a valid external address exists:
+ kubectl get svc ingress-nginx-controller -n ingress-nginx +
+
++ +Bare Metal Clusters
+-
+
- Apply:
+ kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.1.1/deploy/static/provider/baremetal/deploy.yaml +
+ - Verify a valid external address exists:
+ kubectl get svc ingress-nginx-controller -n ingress-nginx +
+
++ +Digital Ocean
+-
+
- Apply:
+ kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.1.1/deploy/static/provider/do/deploy.yaml +
+ - Verify a valid external address exists:
+ kubectl get svc ingress-nginx-controller -n ingress-nginx +
+
++ +Docker Desktop
+-
+
- Apply:
+ kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.1.1/deploy/static/provider/cloud/deploy.yaml +
+ - Verify a valid external address exists:
+ kubectl get svc ingress-nginx-controller -n ingress-nginx +
+
+Note: By default, Docker Desktop services will provision with localhost as their external address. Triggers in delivery pipelines cannot reach this instance unless they originate from the same machine where Docker Desktop is being used. + +++ + +Exoscale
+-
+
- Apply:
+ kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/exoscale/deploy.yaml +
+ - Verify a valid external address exists:
+ kubectl get svc ingress-nginx-controller -n ingress-nginx +
+
++ + +Google (GKE)
+
+Add firewall rules +
+GKE by default limits outbound requests from nodes. For the runtime to communicate with the control-plane in Codefresh, add a firewall-specific rule. + +-
+
- Find your cluster's network:
+ gcloud container clusters describe [CLUSTER_NAME] --format=get"(network)" +
+ - Get the Cluster IPV4 CIDR:
+ gcloud container clusters describe [CLUSTER_NAME] --format=get"(clusterIpv4Cidr)" +
+ - Replace the `[CLUSTER_NAME]`, `[NETWORK]`, and `[CLUSTER_IPV4_CIDR]`, with the relevant values:
+ gcloud compute firewall-rules create "[CLUSTER_NAME]-to-all-vms-on-network"
+ + --network="[NETWORK]" \ +
+ + --source-ranges="[CLUSTER_IPV4_CIDR]" \ +
+ + --allow=tcp,udp,icmp,esp,ah,sctp +
+
+
+Use ingress-nginx
+-
+
- Create a `cluster-admin` role binding:
+ + kubectl create clusterrolebinding cluster-admin-binding \ +
+ + --clusterrole cluster-admin \ +
+ + --user $(gcloud config get-value account) +
+
+ - Apply:
+ + kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.1.1/deploy/static/provider/cloud/deploy.yaml + +
+ - Verify a valid external address exists:
+ kubectl get svc ingress-nginx-controller -n ingress-nginx +
+
+
++ + +MicroK8s
+-
+
- Install using Microk8s addon system:
+ microk8s enable ingress +
+ - Verify a valid external address exists:
+ kubectl get svc ingress-nginx-controller -n ingress-nginx +
+
++ + + +MiniKube
+-
+
- Install using MiniKube addon system:
+ minikube addons enable ingress +
+ - Verify a valid external address exists:
+ kubectl get svc ingress-nginx-controller -n ingress-nginx +
+
++ +Oracle Cloud Infrastructure
+-
+
- Apply:
+ kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.1.1/deploy/static/provider/cloud/deploy.yaml +
+ - Verify a valid external address exists:
+ kubectl get svc ingress-nginx-controller -n ingress-nginx +
+
++ +{::nomarkdown} + +{:/} + +### Traefik ingress configuration +For detailed configuration information, see [Traefik ingress controller documentation](https://doc.traefik.io/traefik/providers/kubernetes-ingress){:target="\_blank}. + +The table below lists the specific configuration requirements for Codefresh. + +{: .table .table-bordered .table-hover} + +| What to configure | When to configure | +| -------------- | -------------- | +|Valid external IP address | _Before_ installing hybrid runtime | +|Valid SSL certificate | | +|TCP support | | +|Enable report status to cluster| | + +{::nomarkdown} + +{:/} + +#### Valid external IP address +Run `kubectl get svc -A` to get a list of services and verify that the `EXTERNAL-IP` column for your ingress controller shows a valid hostname. + +{::nomarkdown} + +{:/} + +#### Valid TLS certificate +For secure runtime installation, the ingress controller must have a valid TLS certificate. +> Use the FQDN (Fully Qualified Domain Name) of the ingress controller for the TLS certificate. + +{::nomarkdown} + +{:/} + +#### TCP support +Configure the ingress controller to handle TCP requests. + +{::nomarkdown} + +{:/} + +#### Enable report status to cluster +By default, the Traefik ingress controller is not configured to report its status to the cluster. If not configured, Argo’s health check reports the health status as “progressing”, resulting in a timeout error during installation. + +To enable reporting its status, add `publishedService` to `providers.kubernetesIngress.ingressEndpoint`. + +The value must be in the format `"Scaleway
+-
+
- Apply:
+ kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.1.1/deploy/static/provider/scw/deploy.yaml +
+ - Verify a valid external address exists:
+ kubectl get svc ingress-nginx-controller -n ingress-nginx +
+
/ "`, where: + ` ` is the Traefik service from which to copy the status + +```yaml +... +providers: + kubernetesIngress: + ingressEndpoint: + publishedService: " / " # Example, "codefresh/traefik-default" +... +``` + +{::nomarkdown} + +{:/} + +## GitOps CLI installation + +### GitOps CLI installation modes +The table lists the modes available to install the Codefresh CLI. + +{: .table .table-bordered .table-hover} +| Install mode | OS | Commands | +| -------------- | ----------| ----------| +| `curl` | MacOS-x64 | `curl -L --output - https://github.com/codefresh-io/cli-v2/releases/latest/download/cf-darwin-amd64.tar.gz | tar zx && mv ./cf-darwin-amd64 /usr/local/bin/cf && cf version`| +| | MacOS-m1 |`curl -L --output - https://github.com/codefresh-io/cli-v2/releases/latest/download/cf-darwin-arm64.tar.gz | tar zx && mv ./cf-darwin-arm64 /usr/local/bin/cf && cf version` | +| | Linux - X64 |`curl -L --output - https://github.com/codefresh-io/cli-v2/releases/latest/download/cf-linux-amd64.tar.gz | tar zx && mv ./cf-linux-amd64 /usr/local/bin/cf && cf version` | +| | Linux - ARM | `curl -L --output - https://github.com/codefresh-io/cli-v2/releases/latest/download/cf-linux-arm64.tar.gz | tar zx && mv ./cf-linux-arm64 /usr/local/bin/cf && cf version`| +| `brew` | N/A| `brew tap codefresh-io/cli && brew install cf2`| + +### Install the GitOps CLI +Install the Codefresh CLI using the option that best suits you: `curl`, `brew`, or standard download. +If you are not sure which OS to select for `curl`, simply select one, and Codefresh automatically identifies and selects the right OS for CLI installation. + +1. Do one of the following: + * For first-time installation, go to the Welcome page, select **+ Install Runtime**. + * If you have provisioned a GitOps Runtime, in the Codefresh UI, go to [GitOps Runtimes](https://g.codefresh.io/2.0/account-settings/runtimes){:target="\_blank"}, and select **+ Add Runtime**. +1. Install the Codefresh CLI: + * Select one of the installation modes. + * Generate the API key. + * Create the authentication context: + `cf config create-context codefresh --api-key ` + + + {% include + image.html + lightbox="true" + file="/images/getting-started/quick-start/quick-start-download-cli.png" + url="/images/getting-started/quick-start/quick-start-download-cli.png" + alt="Download CLI to install runtime" + caption="Download CLI to install runtime" + max-width="30%" + %} + + +{::nomarkdown} + +{:/} + +## Install Hybrid GitOps Runtime + +**Before you begin** +* Make sure you meet the [minimum requirements]({{site.baseurl}}/docs/runtime/requirements/#minimum-requirements) for installation +* Make sure you have [Runtime token with the required scopes from your Git provider]({{site.baseurl}}/docs/reference/git-tokens) +* [Download or upgrade to the latest version of the CLI]({{site.baseurl}}/docs/installation/hybrid-gitops/#hybrid-gitops-upgrade-gitops-cli) +* Review [Hybrid Runtime installation flags](#hybrid-runtime-installation-flags) +* For ingress-based runtimes, make sure your ingress controller is configured correctly: + * [Ambasador ingress configuration]({{site.baseurl}}/docs/runtime/requirements/#ambassador-ingress-configuration) + * [AWS ALB ingress configuration]({{site.baseurl}}/docs/runtime/requirements/#alb-aws-ingress-configuration) + * [Istio ingress configuration]({{site.baseurl}}/docs/runtime/requirements/#istio-ingress-configuration) + * [NGINX Enterprise ingress configuration]({{site.baseurl}}/docs/runtime/requirements/#nginx-enterprise-ingress-configuration) + * [NGINX Community ingress configuration]({{site.baseurl}}/docs/runtime/requirements/#nginx-community-version-ingress-configuration) + * [Traefik ingress configuration]({{site.baseurl}}/docs/runtime/requirements/#traefik-ingress-configuration) + + +{::nomarkdown} + +{:/} + +**How to** + +1. Do one of the following: + * If this is your first Hybrid Runtime installation, in the Welcome page, select **+ Install Runtime**. + * If you have provisioned a Hybrid Runtime, to provision additional runtimes, in the Codefresh UI, go to [**Runtimes**](https://g.codefresh.io/2.0/account-settings/runtimes){:target="\_blank"}. +1. Click **+ Add Runtimes**, and then select **Hybrid Runtimes**. +1. Do one of the following: + * CLI wizard: Run `cf runtime install`, and follow the prompts to enter the required values. + * Silent install: Pass the required flags in the install command: + `cf runtime install --repo --git-token --silent` + For the list of flags, see [Hybrid runtime installation flags](#hybrid-runtime-installation-flags). +1. If relevant, complete the configuration for these ingress controllers: + * [ALB AWS: Alias DNS record in route53 to load balancer]({{site.baseurl}}/docs/runtime/requirements/#alias-dns-record-in-route53-to-load-balancer) + * [Istio: Configure cluster routing service]({{site.baseurl}}/docs/runtime/requirements/#cluster-routing-service) + * [NGINX Enterprise ingress controller: Patch certificate secret]({{site.baseurl}}/docs/runtime/requirements/#patch-certificate-secret) +1. If you bypassed installing ingress resources with the `--skip-ingress` flag for ingress controllers not in the supported list, create and register Git integrations using these commands: + `cf integration git add default --runtime --api-url ` + `cf integration git register default --runtime --token ` + + +{::nomarkdown} + +{:/} + + + +## Hybrid GitOps Runtime installation flags +This section describes the required and optional flags to install a Hybrid GitOps Runtime. +For documentation purposes, the flags are grouped into: +* Runtime flags, relating to Runtime, cluster, and namespace requirements +* Ingress-less flags, for tunnel-based installation +* Ingress-controller flags, for ingress-based installation +* Git provider flags +* Codefresh resource flags + +{::nomarkdown} + +{:/} + +### Runtime flags + +**Runtime name** +Required. +The Runtime name must start with a lower-case character, and can include up to 62 lower-case characters and numbers. +* CLI wizard: Add when prompted. +* Silent install: Add the `--runtime` flag and define the name. + +**Namespace resource labels** +Optional. +The label of the namespace resource to which you are installing the Hybrid Runtime. Labels are required to identify the networks that need access during installation, as is the case when using services meshes, such as Istio for example. + +* CLI wizard and Silent install: Add the `--namespace-labels` flag, and define the labels in `key=value` format. Separate multiple labels with `commas`. + +**Kube context** +Required. +The cluster defined as the default for `kubectl`. If you have more than one Kube context, the current context is selected by default. + +* CLI wizard: Select the Kube context from the list displayed. +* Silent install: Explicitly specify the Kube context with the `--context` flag. + +**Access mode** +The access mode for the runtime, which can be one of the following: +* [Tunnel-based]({{site.baseurl}}/docs/installation/runtime-architecture/#tunnel-based-hybrid-gitops-runtime-architecture), for runtimes without ingress controllers. This is the default. +* [Ingress-based]({{site.baseurl}}/docs/getting-started/architecture/#ingress-based-hybrid-gitops-runtime-architecture) for runtimes with ingress contollers. + + +* CLI wizard: Select the access mode from the list displayed. +* Silent install: + * For tunnel-based, see [Tunnel-based runtime flags](#tunnel-based-runtime-flags) + * For ingress-based, add the [Ingress controller flags](#ingress-controller-flags) + + >If you don't specify any flags, tunnel-based access is automatically selected. + +**Shared configuration repository** +The Git repository per Runtime account with shared configuration manifests. +* CLI wizard and Silent install: Add the `--shared-config-repo` flag and define the path to the shared repo. + +{::nomarkdown} + +{:/} + +### Tunnel-based runtime flags +These flags are required to install tunnel-based Hybrid Runtimes, without an ingress controller. + +**IP allowlist** + +Optional. + +The allowed list of IPs from which to forward requests to the internal customer cluster for ingress-less runtime installations. The allowlist can include IPv4 and IPv6 addresses, with/without subnet and subnet masks. Multiple IPs must be separated by commas. + +When omitted, all incoming requests are authenticated regardless of the IPs from which they originated. + +* CLI wizard and Silent install: Add the `--ips-allow-list` flag, followed by the IP address, or list of comma-separated IPs to define more than one. For example, `--ips-allow-list 77.126.94.70/16,192.168.0.0` + +{::nomarkdown} + +{:/} + +### Ingress controller flags + + +**Skip ingress** +Required, if you are using an unsupported ingress controller. +For unsupported ingress controllers, bypass installing ingress resources with the `--skip-ingress` flag. +In this case, after completing the installation, manually configure the cluster's routing service, and create and register Git integrations. See the last step in [Install the Hybrid GitOps Runtime](#install-hybrid-gitops-runtime). + +**Ingress class** +Required. + +* CLI wizard: Select the ingress class for Runtime installation from the list displayed. +* Silent install: Explicitly specify the ingress class through the `--ingress-class` flag. Otherwise, Runtime installation fails. + +**Ingress host** +Required. +The IP address or host name of the ingress controller component. + +* CLI wizard: Automatically selects and displays the host, either from the cluster or the ingress controller associated with the **Ingress class**. +* Silent install: Add the `--ingress-host` flag. If a value is not provided, takes the host from the ingress controller associated with the **Ingress class**. + > Important: For AWS ALB, the ingress host is created post-installation. However, when prompted, add the domain name you will create in `Route 53` as the ingress host. + +**Insecure ingress hosts** +TLS certificates for the ingress host: +If the ingress host does not have a valid TLS certificate, you can continue with the installation in insecure mode, which disables certificate validation. + +* CLI wizard: Automatically detects and prompts you to confirm continuing the installation in insecure mode. +* Silent install: To continue with the installation in insecure mode, add the `--insecure-ingress-host` flag. + +**Internal ingress host** +Optional. +Enforce separation between internal (app-proxy) and external (webhook) communication by adding an internal ingress host for the app-proxy service in the internal network. +For both CLI wizard and Silent install: + +* For new Runtime installations, add the `--internal-ingress-host` flag pointing to the ingress host for `app-proxy`. +* For existing installations, commit changes to the installation repository by modifying the `app-proxy ingress` and ` .yaml` + See [(Optional) Internal ingress host configuration for existing Hybrid Runtimes](#optional-internal-ingress-host-configuration-for-existing-hybrid-runtimes). + +{::nomarkdown} + +{:/} + + + +### Git provider and repo flags +The Git provider defined for the Runtime. + +>Because Codefresh creates a [shared configuration repo]({{site.baseurl}}/docs/reference/shared-configuration) for the Runtimes in your account, the Git provider defined for the first Runtime you install in your account is used for all the other Runtimes in the same account. + +You can define any of the following Git providers: +* GitHub: + * [GitHub](#github) (the default Git provider) + * [GitHub Enterprise](#github-enterprise) +* GitLab: + * [GitLab Cloud](#gitlab-cloud) + * [GitLab Server](#gitlab-server) +* Bitbucket: + * [Bitbucket Cloud](#bitbucket-cloud) + * [Bitbucket Server](#bitbucket-server) + +{::nomarkdown} + +{:/} + + + +#### GitHub +GitHub is the default Git provider for Hybrid Runtimes. Being the default provider, for both the CLI wizard and Silent install, you need to provide only the repository URL and the Git runtime token. + +> For the required scopes, see [GitHub and GitHub Enterprise Runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#github-and-github-enterprise-runtime-token-scopes). + +`--repo --git-token ` + +where: +* `--repo ` (required), is the `HTTPS` clone URL of the Git repository for the Runtime installation, including the `.git` suffix. Copy the clone URL from your GitHub website (see [Cloning with HTTPS URLs](https://docs.github.com/en/get-started/getting-started-with-git/about-remote-repositories#cloning-with-https-urls){:target="\_blank"}). + If the repo doesn't exist, copy an existing clone URL and change the name of the repo. Codefresh creates the repository during the installation. + + Repo URL format: + `https://github.com/ /reponame>.git[/subdirectory][?ref=branch]` + where: + * ` / ` is your username or organization name, followed by the name of the repo, identical to the HTTPS clone URL. For example, `https://github.com/nr-codefresh/codefresh.io.git`. + * `[/subdirectory]` (optional) is the path to a subdirectory within the repo. When omitted, the Runtime is installed in the root of the repository. For example, `/runtimes/defs`. + * `[?ref=branch]` (optional) is the `ref` queryParam to select a specific branch. When omitted, the Runtime is installed in the default branch. For example, `codefresh-prod`. + + Example: + `https://github.com/nr-codefresh/codefresh.io.git/runtimes/defs?ref=codefresh-prod` +* `--git-token ` (required), is the Git token authenticating access to the Runtime installation repository (see [GitHub runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#github-and-github-enterprise-runtime-token-scopes)). + +{::nomarkdown} + +{:/} + +#### GitHub Enterprise + +> For the required scopes, see [GitHub and GitHub Enterprise runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#github-and-github-enterprise-runtime-token-scopes). + + +`--provider github --repo --git-token ` + +where: +* `--provider github` (required), defines GitHub Enterprise as the Git provider for the Runtime and the account. +* `--repo ` (required), is the `HTTPS` clone URL of the Git repository for the Runtime installation, including the `.git` suffix. Copy the clone URL for HTTPS from your GitHub Enterprise website (see [Cloning with HTTPS URLs](https://docs.github.com/en/get-started/getting-started-with-git/about-remote-repositories#cloning-with-https-urls){:target="\_blank"}). + If the repo doesn't exist, copy an existing clone URL and change the name of the repo. Codefresh creates the repository during the installation. + Repo URL format: + + `https://ghe-trial.devops.cf-cd.com/ / .git[/subdirectory][?ref=branch]` + where: + * ` / ` is your username or organization name, followed by the name of the repo. For example, `codefresh-io/codefresh.io.git`. + * `[/subdirectory]` (optional) is the path to a subdirectory within the repo. When omitted, the Runtime is installed in the root of the repository. For example, `/runtimes/defs`. + * `[?ref=branch]` (optional) is the `ref` queryParam to select a specific branch. When omitted, the Runtime is installed in the default branch. For example, `codefresh-prod`. + + Example: + `https://ghe-trial.devops.cf-cd.com/codefresh-io/codefresh.io.git/runtimes/defs?ref=codefresh-prod` +* `--git-token ` (required), is the Git token authenticating access to the Runtime installation repository (see [GitHub runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#github-and-github-enterprise-runtime-token-scopes)). + + +{::nomarkdown} + +{:/} + +#### GitLab Cloud +> For the required scopes, see [GitLab Cloud and GitLab Server runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#gitlab-cloud-and-gitlab-server-runtime-token-scopes). + + +`--provider gitlab --repo --git-token ` + +where: +* `--provider gitlab` (required), defines GitLab Cloud as the Git provider for the Runtime and the account. +* `--repo ` (required), is the `HTTPS` clone URL of the Git project for the Runtime installation, including the `.git` suffix. Copy the clone URL for HTTPS from your GitLab website. + If the repo doesn't exist, copy an existing clone URL and change the name of the repo. Codefresh creates the repository during the installation. + + > Important: You must create the group with access to the project prior to the installation. + + Repo URL format: + + `https://gitlab.com/ / .git[/subdirectory][?ref=branch]` + where: + * ` ` is either your username, or if your project is within a group, the front-slash separated path to the project. For example, `nr-codefresh` (owner), or `parent-group/child-group` (group hierarchy) + * ` ` is the name of the project. For example, `codefresh`. + * `[/subdirectory]` (optional) is the path to a subdirectory within the repo. When omitted, the Runtime is installed in the root of the repository. For example, `/runtimes/defs`. + * `[?ref=branch]` (optional) is the `ref` queryParam to select a specific branch. When omitted, the Runtime is installed in the default branch. For example, `codefresh-prod`. + + Examples: + `https://gitlab.com/nr-codefresh/codefresh.git/runtimes/defs?ref=codefresh-prod` (owner) + + `https://gitlab.com/parent-group/child-group/codefresh.git/runtimes/defs?ref=codefresh-prod` (group hierarchy) + +* `--git-token ` (required), is the Git token authenticating access to the Runtime installation repository (see [GitLab runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#gitlab-cloud-and-gitlab-server-runtime-token-scopes)). + + +{::nomarkdown} + +{:/} + + +#### GitLab Server + +> For the required scopes, see [GitLab Cloud and GitLab Server runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#gitlab-cloud-and-gitlab-server-runtime-token-scopes). + +`--provider gitlab --repo --git-token ` + +where: +* `--provider gitlab` (required), defines GitLab Server as the Git provider for the Runtime and the account. +* `--repo ` (required), is the `HTTPS` clone URL of the Git repository for the Runtime installation, including the `.git` suffix. + If the project doesn't exist, copy an existing clone URL and change the name of the project. Codefresh creates the project during the installation. + + > Important: You must create the group with access to the project prior to the installation. + + Repo URL format: + `https://gitlab-onprem.devops.cf-cd.com/ / .git[/subdirectory][?ref=branch]` + where: + * ` ` is your username, or if the project is within a group or groups, the name of the group. For example, `nr-codefresh` (owner), or `parent-group/child-group` (group hierarchy) + * ` ` is the name of the project. For example, `codefresh`. + * `[/subdirectory]` (optional) is the path to a subdirectory within the repo. When omitted, the Runtime is installed in the root of the repository. For example, `/runtimes/defs`. + * `[?ref=branch]` (optional) is the `ref` queryParam to select a specific branch. When omitted, the Runtime is installed in the default branch. For example, `codefresh-prod`. + + Examples: + `https://gitlab-onprem.devops.cf-cd.com/nr-codefresh/codefresh.git/runtimes/defs?ref=codefresh-prod` (owner) + + `https://gitlab-onprem.devops.cf-cd.com/parent-group/child-group/codefresh.git/runtimes/defs?ref=codefresh-prod` (group hierarchy) + +* `--git-token ` (required), is the Git token authenticating access to the Runtime installation repository (see [GitLab runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#gitlab-cloud-and-gitlab-server-runtime-token-scopes)). + + +{::nomarkdown} + +{:/} + +#### Bitbucket Cloud +> For the required scopes, see [Bitbucket runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#bitbucket-cloud-and-bitbucket-server-runtime-token-scopes). + + +`--provider bitbucket --repo --git-user --git-token ` + +where: +* `--provider gitlab` (required), defines Bitbucket Cloud as the Git provider for the Runtime and the account. +* `--repo ` (required), is the `HTTPS` clone URL of the Git repository for the Runtime installation, including the `.git` suffix. + If the project doesn't exist, copy an existing clone URL and change the name of the project. Codefresh creates the project during Runtime installation. + >Important: Remove the username, including @ from the copied URL. + + Repo URL format: + + `https://bitbucket.org .git[/subdirectory][?ref=branch]` + where: + * ` ` is your workspace ID. For example, `nr-codefresh`. + * ` ` is the name of the repository. For example, `codefresh`. + * `[/subdirectory]` (optional) is the path to a subdirectory within the repo. When omitted, the Runtime is installed in the root of the repository. For example, `/runtimes/defs`. + * `[?ref=branch]` (optional) is the `ref` queryParam to select a specific branch. When omitted, the Runtime is installed in the default branch. For example, `codefresh-prod`. + + Example: + `https://bitbucket.org/nr-codefresh/codefresh.git/runtimes/defs?ref=codefresh-prod` +* `--git-user ` (required), is your username for the Bitbucket Cloud account. +* `--git-token ` (required), is the Git token authenticating access to the runtime installation repository (see [Bitbucket runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#bitbucket-cloud-and-bitbucket-server-runtime-token-scopes)). + + +{::nomarkdown} + +{:/} + +#### Bitbucket Server + +> For the required scopes, see [Bitbucket runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#bitbucket-cloud-and-bitbucket-server-runtime-token-scopes). + + +`--provider bitbucket-server --repo --git-user --git-token ` + +where: +* `--provider gitlab` (required), defines Bitbucket Cloud as the Git provider for the Runtime and the account. +* `--repo ` (required), is the `HTTPS` clone URL of the Git repository for the Runtime installation, including the `.git` suffix. + If the project doesn't exist, copy an existing clone URL and change the name of the project. Codefresh then creates the project during the installation. + >Important: Remove the username, including @ from the copied URL. + + Repo URL format: + + `https://bitbucket-server-8.2.devops.cf-cd.com:7990/scm/ / .git[/subdirectory][?ref=branch]` + where: + * ` ` is your username or organization name. For example, `codefresh-io.`. + * ` ` is the name of the repo. For example, `codefresh`. + * `[/subdirectory]` (optional) is the path to a subdirectory within the repo. When omitted, the Runtime is installed in the root of the repository. For example, `/runtimes/defs`. + * `[?ref=branch]` (optional) is the `ref` queryParam to select a specific branch. When omitted, the Runtime is installed in the default branch. For example, `codefresh-prod`. + + Example: + `https://bitbucket-server-8.2.devops.cf-cd.com:7990/scm/codefresh-io/codefresh.git/runtimes/defs?ref=codefresh-prod` +* `--git-user ` (required), is your username for the Bitbucket Server account. +* `--git-token ` (required), is the Git token authenticating access to the Runtime installation repository (see [Bitbucket runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#bitbucket-cloud-and-bitbucket-server-runtime-token-scopes)). + +{::nomarkdown} + +{:/} + +### Codefresh resource flags +**Codefresh demo resources** +Optional. +Install demo pipelines to use as a starting point to create your own GitOps pipelines. We recommend installing the demo resources as these are used in our quick start tutorials. + +* Silent install: Add the `--demo-resources` flag, and define its value as `true` (default), or `false`. For example, `--demo-resources=true` + +**Insecure flag** +For _on-premises installations_, if the Ingress controller does not have a valid SSL certificate, to continue with the installation, add the `--insecure` flag to the installation command. + +{::nomarkdown} + +{:/} + + + + + + + +## (Optional) Internal ingress host configuration for existing Hybrid Runtimes +If you already have provisioned Hybrid Runtimes, to use an internal ingress host for app-proxy communication and an external ingress host to handle webhooks, change the specs for the `Ingress` and `Runtime` resources in the Runtime installation repository. Use the examples as guidelines. + +` /apps/app-proxy/overlays/ /ingress.yaml`: change `host` + +```yaml +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: codefresh-cap-app-proxy + namespace: codefresh #replace with your runtime name +spec: + ingressClassName: nginx + rules: + - host: my-internal-ingress-host # replace with the internal ingress host for app-proxy + http: + paths: + - backend: + service: + name: cap-app-proxy + port: + number: 3017 + path: /app-proxy/ + pathType: Prefix +``` + +`../ /bootstrap/ .yaml`: add `internalIngressHost` + +```yaml +apiVersion: v1 +data: + base-url: https://g.codefresh.io + runtime: | + apiVersion: codefresh.io/v1alpha1 + kind: Runtime + metadata: + creationTimestamp: null + name: codefresh #replace with your runtime name + namespace: codefresh #replace with your runtime name + spec: + bootstrapSpecifier: github.com/codefresh-io/cli-v2/manifests/argo-cd + cluster: https://7DD8390300DCEFDAF87DC5C587EC388C.gr7.us-east-1.eks.amazonaws.com + components: + - isInternal: false + name: events + type: kustomize + url: github.com/codefresh-io/cli-v2/manifests/argo-events + wait: true + - isInternal: false + name: rollouts + type: kustomize + url: github.com/codefresh-io/cli-v2/manifests/argo-rollouts + wait: false + - isInternal: false + name: workflows + type: kustomize + url: github.com/codefresh-io/cli-v2/manifests/argo-workflows + wait: false + - isInternal: false + name: app-proxy + type: kustomize + url: github.com/codefresh-io/cli-v2/manifests/app-proxy + wait: false + defVersion: 1.0.1 + ingressClassName: nginx + ingressController: k8s.io/ingress-nginx + ingressHost: https://support.cf.com/ + internalIngressHost: https://my-internal-ingress-host # add this line and replace my-internal-ingress-host with your internal ingress host + repo: https://github.com/NimRegev/my-codefresh.git + version: 99.99.99 +``` + + +## Related articles +[Add external clusters to Hybrid and Hosted Runtimes]({{site.baseurl}}/docs/installation/managed-cluster/) +[Monitoring & managing GitOps Runtimes]({{site.baseurl}}/docs/installation/monitor-manage-runtimes/) +[Add Git Sources to runtimes]({{site.baseurl}}/docs/installation/git-sources/) +[Shared configuration repo]({{site.baseurl}}/docs/reference/shared-configuration) +[Troubleshoot Hybrid Runtime installation]({{site.baseurl}}/installation/troubleshooting/runtime-issues/) diff --git a/_docs/installation/installation-options.md b/_docs/installation/installation-options.md new file mode 100644 index 00000000..f88b9fe9 --- /dev/null +++ b/_docs/installation/installation-options.md @@ -0,0 +1,231 @@ +--- +title: "Installation environments" +description: "" +group: installation +toc: true +--- +To be changed and updated for ProjectOne + +The Codefresh platform supports two different installation environments, each with different installation options. + +* CI/CD installation environment + The CI/CD installation environment is optimized for Continuous Integration/Delivery with Codefresh pipelines. CI pipelines created in Codefresh fetch code from your Git repository, packages/compiles the code, and deploys the final artifact to a target environment. + + The CI/CD installation environment supports these installation options: + * Hybrid, where the Codefresh CI/CD UI runs in the Codefresh cloud, and the builds run on customer premises + * SaaS, a full cloud version that is fully managed by Codefresh + * On-premises, where Codefresh CI/CD runs within the customer datacenter/cloud + + On-premises and Hybrid CI/CD options are available to Enterprise customers looking for a "behind-the-firewall" solution. + +* GitOps installation environment + The GitOps installation environment is a full-featured solution for application deployments and releases. Powered by the Argo Project, Codefresh uses Argo CD, Argo Workflows, Argo Events, and Argo Rollouts, extended with unique functionality and features essential for enterprise deployments. + + GitOps installations support Hosted and Hybrid options. + +## Comparison +Both environments can co-exist giving you the best of both worlds. For + +TBD + + +## Codefresh CI/CD installation options + + + + + + + + + +### Codefresh Cloud CI/CD - likely to be removed + +The Codefresh CI/CD Cloud version is the easiest way to start using Codefresh as it is fully managed and runs 100% on the cloud. Codefresh DevOps handles the maintenance and updates. + +You can also create a [free account]({{site.baseurl}}/docs/getting-started/create-a-codefresh-account/) on the SAAS version right away. The account is forever free with some limitations +on number of builds. + +The cloud version runs on multiple clouds: + +{% include image.html + lightbox="true" + file="/images/administration/installation/codefresh-saas.png" + url="/images/administration/installation/codefresh-saas.png" + alt="sso-diagram.png" + max-width="60%" + %} + +Codefresh Cloud is also compliant with [SOC2 - Type2](https://www.aicpa.org/SOC) showing our commitment to security and availability. + +{% include image.html + lightbox="true" + file="/images/administration/installation/soc2-type2-certified.png" + url="/images/administration/installation/soc2-type2-certified.png" + alt="sso-diagram.png" + max-width="40%" + %} + +The Cloud version has multi-account support with most git providers (GitLab, GitHub, Bitbucket) as well as Azure and Google. + + +### Codefresh Hybrid CI/CD + +The Hybrid CI/CD installation option is for organizations who want their source code to live within their premises, or have other security constraints. For more about the theory and implementation, see [CI/CD behind the firewall installation]({{site.baseurl}}/docs/administration/behind-the-firewall/). + +The UI runs on Codefresh infrastructure, while the builds happen in a Kubernetes cluster in the customer's premises. + +{% include image.html + lightbox="true" + file="/images/administration/installation/hybrid-installation.png" + url="/images/administration/installation/hybrid-installation.png" + alt="sso-diagram.png" + max-width="70%" + %} + + +CI/CD Hybrid installation strikes the perfect balance between security, flexibility, and ease of use. Codefresh still does the heavy lifting for maintaining most of the platform parts. The sensitive data (such as source code and internal services) never leave the premises of the customers. + +With Hybrid CI/CD installation, Codefresh can easily connect to internal [secure services]({{site.baseurl}}/docs/reference/behind-the-firewall/#using-secure-services-in-your-pipelines) that have no public presence. +The UI part is still compliant with Soc2. + + +Here are the security implications of CI/CD Hybrid installation: + +{: .table .table-bordered .table-hover} +| Company Asset | Flow/Storage of data | Comments | +| -------------- | ---------------------------- |-------------------------| +| Source code | Stays behind the firewall | | +| Binary artifacts | Stay behind the firewall | | +| Build logs | Also sent to Codefresh Web application | | +| Pipeline volumes | Stay behind the firewall | | +| Pipeline variables | Defined in Codefresh Web application | | +| Deployment docker images | Stay behind the firewall| Stored on your Docker registry | +| Development docker images | Stay behind the firewall | Stored on your Docker registry| +| Testing docker images | Stay behind the firewall| Stored on your Docker registry | +| Inline pipeline definition | Defined in Codefresh Web application | | +| Pipelines as YAML file | Stay behind the firewall | | +| Test results | Stay behind the firewall | | +| HTML Test reports | Shown on Web application | Stored in your S3 or Google bucket or Azure storage | +| Production database data | Stays behind the firewall | | +| Test database data | Stays behind the firewall | | +| Other services (e.g. Queue, ESB) | Stay behind the firewall | | +| Kubernetes deployment specs | Stay behind the firewall | | +| Helm charts | Stay behind the firewall | | +| Other deployment resources/script (e.g. terraform) | Stay behind the firewall | | +| Shared configuration variables | Defined in Codefresh Web application | | +| Deployment secrets (from git/Puppet/Vault etc) | Stay behind the firewall| | +| Audit logs | Managed via Codefresh Web application | | +| SSO/Idp Configuration | Managed via Codefresh Web application | | +| User emails | Managed via Codefresh Web application | | +| Access control rules | Managed via Codefresh Web application | | + + + +### Codefresh On-premises CI/CD + +For customers who want full control, Codefresh also offers an on-premises option for CI/CD installation. Both the UI and builds run on a Kubernetes cluster fully managed by the customer. + +While Codefresh can still help with maintenance of the CI/CD On-premises, we would recommend the Hybrid CI/CD option first as it offers the most flexibility while maintaining high security. + +### CI/CD installation comparison + +{: .table .table-bordered .table-hover} +| Characteristic | Cloud | Hybrid | On Premise | +| -------------- | ---------------------------- |-------------------------| +| Managed by | Codefresh | Codefresh and Customer | Customer | +| UI runs on | public cloud | public cloud | private cluster | +| Builds run on | public cloud | private cluster | private cluster | +| Access to secure/private services | no | yes | yes | +| Customer maintenance effort | none | some | full | +| Best for | most companies | companies with security constraints | Large scale installations | +| Available to | all customers | [enterprise plans](https://codefresh.io/contact-us/) | [enterprise plans](https://codefresh.io/contact-us/) | + + +## Codefresh GitOps installation options + +Similar to CI/CD installation options, Codefresh GitOps also supports SaaS and hybrid installation options: + + +### Hosted GitOps +The SaaS version of GitOps, has Argo CD installed in the Codefresh cluster. +Hosted GitOps Runtime is installed and provisioned in a Codefresh cluster, and managed by Codefresh. +Hosted enviroments are full-cloud environments, where all updates and improvements are managed by Codefresh, with zero-maintenance overhead for you as the customer. Currently, you can add one Hosted GitOps Runtime per account. +For the architecture, see [Hosted GitOps Runtime architecture]({{site.baseurl}}/docs/installation/architecture/#hosted-gitops-runtime-architecture). + + +{% include + image.html + lightbox="true" + file="/images/runtime/intro-hosted-hosted-initial-view.png" + url="/images/runtime/intro-hosted-hosted-initial-view.png" + alt="Hosted runtime setup" + caption="Hosted runtime setup" + max-width="80%" +%} + + For more information on how to set up the hosted environment, including provisioning hosted runtimes, see [Set up Hosted GitOps]({{site.baseurl}}/docs/installation/hosted-runtime/). + +### Hybrid GitOps +The hybrid version of GitOps, has Argo CD installed in the customer's cluster. +Hybrid GitOps is installed in the customer's cluster, and managed by the customer. +The Hybrid GitOps Runtime is optimal for organizations with security constraints, wanting to manage CI/CD operations within their premises. Hybrid GitOps strikes the perfect balance between security, flexibility, and ease of use. Codefresh maintains and manages most aspects of the platform, apart from installing and upgrading Hybrid GitOps Runtimes which are managed by the customer. + + +{% include + image.html + lightbox="true" + file="/images/runtime/runtime-list-view.png" + url="/images/runtime/runtime-list-view.png" + alt="Runtime List View" + caption="Runtime List View" + max-width="70%" +%} + + For more information on hybrid environments, see [Hybrid GitOps runtime requirements]({{site.baseurl}}/docs/installation/hybrid-gitops/#minimum-system-requirements) and [Installling Hybrid GitOps Runtimes]({{site.baseurl}}/docs/installation/hybrid-gitops/). + + + + + +### Hosted vs.Hybrid GitOps + +The table below highlights the main differences between Hosted and Hybrid GitOps. + +{: .table .table-bordered .table-hover} +| GitOps Functionality |Feature | Hosted | Hybrid | +| -------------- | -------------- |--------------- | --------------- | +| Runtime | Installation | Provisioned by Codefresh | Provisioned by customer | +| | Runtime cluster | Managed by Codefresh | Managed by customer | +| | Number per account | One runtime | Multiple runtimes | +| | External cluster | Managed by customer | Managed by customer | +| | Upgrade | Managed by Codefresh | Managed by customer | +| | Uninstall | Managed by customer | Managed by customer | +| Argo CD | | Codefresh cluster | Customer cluster | +| CI Ops | Delivery Pipelines |Not supported | Supported | +| |Workflows | Not supported | Supported | +| |Workflow Templates | Not supported | Supported | +| CD Ops |Applications | Supported | Supported | +| |Image enrichment | Supported | Supported | +| | Rollouts | Supported | Supported | +|Integrations | | Supported | Supported | +|Dashboards |Home Analytics | Hosted runtime and deployments|Runtimes, deployments, Delivery Pipelines | +| |DORA metrics | Supported |Supported | +| |Applications | Supported |Supported | + +### Related articles +[Architecture]({{site.baseurl}}/docs/installation/runtime-architecture/) +[Add Git Sources to GitOps Runtimes]({{site.baseurl}}/docs/installation/git-sources/) +[Shared configuration repository]({{site.baseurl}}/docs/reference/shared-configuration) + diff --git a/_docs/runtime/managed-cluster.md b/_docs/installation/managed-cluster.md similarity index 69% rename from _docs/runtime/managed-cluster.md rename to _docs/installation/managed-cluster.md index 25ae4546..fb010209 100644 --- a/_docs/runtime/managed-cluster.md +++ b/_docs/installation/managed-cluster.md @@ -1,42 +1,42 @@ --- -title: "Add external clusters to runtimes" +title: "Add external clusters to GitOps Runtimes" description: "" -group: runtime +group: installation toc: true --- -Register external clusters to provisioned hybrid or hosted runtimes in Codefresh. Once you add an external cluster, you can deploy applications to that cluster without having to install Argo CD in order to do so. External clusters allow you to manage multiple clusters through a single runtime. +Register external clusters to provisioned Hybrid or Hosted GitOps Runtimes in Codefresh. Once you add an external cluster, you can deploy applications to that cluster without having to install Argo CD in order to do so. Manage manage multiple external clusters through a single Runtime. -When you add an external cluster to a provisioned runtime, the cluster is registered as a managed cluster. A managed cluster is treated as any other managed K8s resource, meaning that you can monitor its health and sync status, deploy applications on the cluster and view information in the Applications dashboard, and remove the cluster from the runtime's managed list. +When you add an external cluster to a provisioned Runtime, the cluster is registered as a managed cluster. A managed cluster is treated as any other managed K8s resource, meaning that you can monitor its health and sync status, deploy applications to it, view information in the Applications dashboard, and remove the cluster from the Runtime's managed list. Add managed clusters through: * Codefresh CLI * Kustomize -Adding a managed cluster via Codefresh ensures that Codefresh applies the required RBAC resources (`ServiceAccount`, `ClusterRole` and `ClusterRoleBinding`) to the target cluster, creates a `Job` that updates the selected runtime with the information, registers the cluster in Argo CD as a managed cluster, and updates the platform with the new cluster information. +Adding a managed cluster via Codefresh ensures that Codefresh applies the required RBAC resources (`ServiceAccount`, `ClusterRole` and `ClusterRoleBinding`) to the target cluster, creates a `Job` that updates the selected Runtime with the information, registers the cluster in Argo CD as a managed cluster, and updates the platform with the new cluster information. -### Add a managed cluster with Codefresh CLI -Add an external cluster to a provisioned runtime through the Codefresh CLI. When adding the cluster, you can also add labels and annotations to the cluster, which are added to the cluster secret created by Argo CD. +## Add a managed cluster with Codefresh CLI +Add an external cluster to a provisioned GitOps Runtime through the Codefresh CLI. When adding the cluster, you can also add labels and annotations to the cluster, which are added to the cluster secret created by Argo CD. Optionally, to first generate the YAML manifests, and then manually apply them, use the `dry-run` flag in the CLI. **Before you begin** - -* For _hosted_ runtimes: [Configure access to these IP addresses]({{site.baseurl}}/docs/administration/platform-ip-addresses/) +* For _Hosted_ Runtimes: [Configure access to these IP addresses]({{site.baseurl}}/docs/administration/platform-ip-addresses/) * Verify that: - * Your Git personal access token is valid and has the correct permissions - * You have installed the latest version of the Codefresh CLI + * Your Git personal access token is valid and has the [required scopes]({{site.baseurl}}/docs/reference/git-tokens) + * You have installed the [latest version of the Codefresh CLI]({{site.baseurl}}/docs/installation/monitor-manage-runtimes/#hybrid-gitops-upgrade-gitops-cli) **How to** -1. In the Codefresh UI, go to [Runtimes](https://g.codefresh.io/2.0/account-settings/runtimes){:target="\_blank"}. -1. From either the **Topology** or **List** views, select the runtime to which to add the cluster. +1. In the Codefresh UI, go to [GitOps Runtimes](https://g.codefresh.io/2.0/account-settings/runtimes){:target="\_blank"}. +1. From either the **Topology** or **List** views, select the Runtime to which to add the cluster. 1. Topology View: Select {::nomarkdown} 
{:/}.
List View: Select the **Managed Clusters** tab, and then select **+ Add Cluster**.
1. In the Add Managed Cluster panel, copy and run the command:
- `cf cluster add [--labels label-key=label-value] [--annotations annotation-key=annotation-value][--dry-run]` + `cf cluster add [runtime-name] [--labels label-key=label-value] [--annotations annotation-key=annotation-value][--dry-run]` where: + * `runtime-name` is the name of the Runtime to which to add the cluster. * `--labels` is optional, and required to add labels to the cluster. When defined, add a label in the format `label-key=label-value`. Separate multiple labels with `commas`. * `--annotations` is optional, and required to add annotations to the cluster. When defined, add an annotation in the format `annotation-key=annotation-value`. Separate multiple annotations with `commas`. * `--dry-run` is optional, and required if you want to generate a list of YAML manifests that you can redirect and apply manually with `kubectl`. @@ -54,7 +54,7 @@ Optionally, to first generate the YAML manifests, and then manually apply them, {:start="5"} 1. If you used `dry-run`, apply the generated manifests to the same target cluster on which you ran the command. - Here is an example of the YAML manifest generated with the `--dry-run` flag. Note that there are placeholders in the example, which are replaced with the actual values with `--dry-run`. + Here is an example of the YAML manifest generated with the `--dry-run` flag. Note that the example has placeholders, which are replaced with the actual values during the `--dry-run`. ```yaml @@ -177,9 +177,9 @@ spec: ``` -The new cluster is registered to the runtime as a managed cluster. +The new cluster is registered to the Runtime as a managed cluster. -### Add a managed cluster with Kustomize +## Add a managed cluster with Kustomize Create a `kustomization.yaml` file with the information shown in the example below, and run `kustomize build` on it. ```yaml @@ -222,16 +222,20 @@ resources: ``` -### Work with managed clusters -Work with managed clusters in hybrid or hosted runtimes in either the Topology or List runtime views. For information on runtime views, see [Runtime views]({{site.baseurl}}/docs/runtime/runtime-views). -As the cluster is managed through the runtime, updates to the runtime automatically updates the components on all the managed clusters that include it. +## Work with managed clusters +Work with managed clusters in either the Topology or List Runtime views. For information on Runtime views, see [Runtime views]({{site.baseurl}}/docs/runtime/runtime-views). +As the cluster is managed through the Runtime, updates to the Runtime automatically updates the components on all the managed clusters that include it. View connection status for the managed cluster, and health and sync errors. Health and sync errors are flagged by the error notification in the toolbar, and visually flagged in the List and Topology views. -#### Install Argo Rollouts -Install Argo Rollouts directly from Codefresh with a single click to visualize rollout progress in the [Applications dashboard]({{site.baseurl}}/docs/deployment/applications-dashboard/). If Argo Rollouts has not been installed, an **Install Argo Rollouts** button is displayed on selecting the managed cluster. +### Install Argo Rollouts +Applications with `rollout` resources need Argo Rollouts on the target cluster, both to visualize rollouts in the Applications dashboard and control rollout steps with the Rollout Player. +If Argo Rollouts has not been installed on the target cluster, it displays **Install Argo Rollouts** button. + +Install Argo Rollouts with a single click to execute rollout instructions, deploy the application, and visualize rollout progress in the [Applications dashboard]({{site.baseurl}}/docs/deployment/applications-dashboard/). + -1. In the Codefresh UI, go to [Runtimes](https://g.codefresh.io/2.0/account-settings/runtimes){:target="\_blank"}. +1. In the Codefresh UI, go to [GitOps Runtimes](https://g.codefresh.io/2.0/account-settings/runtimes){:target="\_blank"}. 1. Select **Topology View**. 1. Select the target cluster, and then select **+ Install Argo Rollouts**. @@ -246,16 +250,16 @@ Install Argo Rollouts directly from Codefresh with a single click to visualize r %} -#### Remove a managed cluster from the Codefresh UI -Remove a cluster from the runtime's list of managed clusters from the Codefresh UI. +### Remove a managed cluster from the Codefresh UI +Remove a cluster from the Runtime's list of managed clusters from the Codefresh UI. > You can also remove it through the CLI. -1. In the Codefresh UI, go to [Runtimes](https://g.codefresh.io/2.0/account-settings/runtimes){:target="\_blank"}. +1. In the Codefresh UI, go to [GitOps Runtimes](https://g.codefresh.io/2.0/account-settings/runtimes){:target="\_blank"}. 1. Select either the **Topology View** or the **List View** tabs. 1. Do one of the following: - * In the Topology View, select the cluster node from the runtime it is registered to. - * In the List View, select the runtime, and then select the **Managed Clusters** tab. + * In the Topology View, select the cluster node from the Runtime it is registered to. + * In the List View, select the Runtime, and then select the **Managed Clusters** tab. 1. Select the three dots next to the cluster name, and then select **Uninstall** (Topology View) or **Remove** (List View). {% include @@ -269,8 +273,8 @@ Remove a cluster from the runtime's list of managed clusters from the Codefresh %} -#### Remove a managed cluster through the Codefresh CLI -Remove a cluster from the list managed by the runtime, through the CLI. +### Remove a managed cluster through the Codefresh CLI +Remove a cluster from the list managed by the Runtime, through the CLI. * Run: `cf cluster remove --server-url ` @@ -279,7 +283,6 @@ Remove a cluster from the list managed by the runtime, through the CLI. ` ` is the URL of the server on which the managed cluster is installed. -### Related articles -[Add Git Sources to runtimes]({{site.baseurl}}/docs/runtime/git-sources/) -[Manage provisioned hybrid runtimes]({{site.baseurl}}/docs/runtime/monitor-manage-runtimes/) -[(Hybrid) Monitor provisioned runtimes]({{site.baseurl}}/docs/runtime/monitoring-troubleshooting/) \ No newline at end of file +## Related articles +[Add Git Sources to GitOps Runtimes]({{site.baseurl}}/docs/installation/git-sources/) +[Monitoring & managing GitOps Runtimes]({{site.baseurl}}/docs/installation/monitor-manage-runtimes/) diff --git a/_docs/installation/monitor-manage-runtimes.md b/_docs/installation/monitor-manage-runtimes.md new file mode 100644 index 00000000..08267a95 --- /dev/null +++ b/_docs/installation/monitor-manage-runtimes.md @@ -0,0 +1,643 @@ +--- +title: "Monitoring & managing GitOps Runtimes" +description: "" +group: runtime +redirect_from: + - /monitor-manage-runtimes/ + - /monitor-manage-runtimes +toc: true +--- + + +The **Runtimes** page displays the provisioned GitOps Runtimes in your account, both Hybrid, and the Hosted Runtime if you have one. + +View Runtime components and information in List or Topology view formats to monitor and manage them. + +{% include + image.html + lightbox="true" + file="/images/runtime/runtime-list-view.png" + url="/images/runtime/runtime-list-view.png" + alt="Runtime List View" + caption="Runtime List View" + max-width="70%" +%} + +Monitor provisioned GitOps Runtimes for security, health, and sync errors: + +* (Hybrid and Hosted) View/download logs for Runtimes and for Runtime components +* (Hybrid) Restore provisioned Runtimes +* (Hybrid) Configure browsers to allow access to insecure Runtimes +* (Hybrid) Monitor notifications in the Activity Log + + +Manage provisioned GitOps Runtimes: +* [Add managed clusters to GitOps Runtimes]({{site.baseurl}}/docs/installation/managed-cluster/) +* [Add and manage Git Sources for GitOps Runtimes]({{site.baseurl}}/docs/installation/git-sources/) +* +* Upgrade GitOps CLI +* Upgrade Hybrid GitOps Runtimes +* Uninstall GitOps Runtimes + + + +> Unless specified otherwise, all options are common to both types of GitOps Runtimes. If an option is valid only for Hybrid GitOps, it is indicated as such. + + +## GitOps Runtime views + +View provisioned GitOps Runtimes in List or Topology view formats. + +* List view: The default view, displays the list of provisioned Runtimes, the clusters managed by them, and Git Sources associated with them. +* Topology view: Displays a hierarchical view of Runtimes and the clusters managed by them, with health and sync status of each cluster. + +### List view + +The List view is a grid-view of the provisioned Runtimes. + +Here is an example of the List view for runtimes. +{% include + image.html + lightbox="true" + file="/images/runtime/runtime-list-view.png" + url="/images/runtime/runtime-list-view.png" + alt="Runtime List View" + caption="Runtime List View" + max-width="70%" +%} + +Here is a description of the information in the List View. + +{: .table .table-bordered .table-hover} +| List View Item| Description | +| -------------- | ---------------- | +|**Name**| The name of the provisioned GitOps Runtime. | +|**Type**| The type of GitOps Runtime provisioned, and can be **Hybrid** or **Hosted**. | +|**Cluster/Namespace**| The K8s API server endpoint, as well as the namespace with the cluster. | +|**Modules**| The modules installed based on the type of provisioned Runtime. Hybrid Runtimes include CI amnd CD Ops modules. Hosted runtimes include CD Ops. | +|**Managed Cluster**| The number of managed clusters if any, for the runtime. To view list of managed clusters, select the runtime, and then the **Managed Clusters** tab. To work with managed clusters, see [Adding external clusters to runtimes]({{site.baseurl}}/docs/runtime/managed-cluster).| +|**Version**| The version of the runtime currently installed. **Update Available!** indicates there are later versions of the runtime. To see all the commits to the runtime, mouse over **Update Available!**, and select **View Complete Change Log**. +|**Last Updated**| The most recent update information from the runtime to the Codefresh platform. Updates are sent to the platform typically every few minutes. Longer update intervals may indicate networking issues.| +|**Sync Status**| The health and sync status of the runtime or cluster. {::nomarkdown} -
indicates health or sync errors in the runtime, or a managed cluster if one was added to the runtime. The runtime name is colored red. 
indicates that the runtime is being synced to the cluster on which it is provisioned.
indicates the local cluster, always displayed as `in-cluster`. The in-cluster server URL is always set to `https://kubernetes.default.svc/`.
indicates a managed cluster.- select to add a new managed cluster.
- indicates health or sync errors in the Runtime, or a managed cluster if one was added to the runtime. The runtime or cluster node is bordered in red and the name is colored red.
- indicates that the Runtime is being synced to the cluster on which it is provisioned.
- Find a Runtime or its clusters by typing part of the Runtime/cluster name, and then navigate to the entries found.
- Topology view options: Resize to window, zoom in, zoom out, full screen view.
--git-token --silent` + where: + ` ` is a valid Git token with the correct scopes. + +**CLI wizard-based upgrade** + +1. In the Codefresh UI, make sure you are in [GitOps Runtimes](https://g.codefresh.io/2.0/account-settings/runtimes){:target="\_blank"}. +1. Switch to either the **List View** or to the **Topology View**. +1. **List view**: + * Select the Runtime name. + * To see all the commits to the Runtime, in the Version column, mouse over **Update Available!**, and select **View Complete Change Log**. + * On the top-right, select **Upgrade**. + + {% include + image.html + lightbox="true" + file="/images/runtime/runtime-list-view-upgrade.png" + url="/images/runtime/runtime-list-view-upgrade.png" + alt="List View: Upgrade runtime option" + caption="List View: Upgrade runtime option" + max-width="30%" + %} + + **Topology view**: + Select the Runtime cluster, and from the panel, select the three dots and then select **Upgrade Runtime**. + {% include + image.html + lightbox="true" + file="/images/runtime/runtiime-topology-upgrade.png" + url="/images/runtime/runtiime-topology-upgrade.png" + alt="Topology View: Upgrade runtime option" + caption="Topology View: Upgrade runtime option" + max-width="30%" +%} + +{:start="4"} + +1. If you have already installed the Codefresh CLI, in the Install Upgrades panel, copy the upgrade command. + + {% include + image.html + lightbox="true" + file="/images/runtime/install-upgrades.png" + url="/images/runtime/install-upgrades.png" + alt="Upgrade runtime" + caption="Upgrade runtime panel" + max-width="30%" +%} + +{:start="5"} +1. In your terminal, paste the command, and do the following: + * Update the Git token value. + * To manually define the shared configuration repo, add the `--shared-config-repo` flag with the path to the repo. +1. Confirm to start the upgrade. + + + + + + +### Uninstall provisioned GitOps Runtimes + +Uninstall provisioned GitOps Runtimes that are not in use. Uninstall a Runtime through a silent uninstall or through the CLI wizard. +> Uninstalling a Runtime removes the Git Sources and managed clusters associated with it. + +**Before you begin** +For both types of uninstalls, make sure you have: + +* The latest version of the GitOps CLI +* A valid runtime Git token +* The Kube context from which to uninstall the provisioned Runtime + +**Silent uninstall** +Pass the mandatory flags in the uninstall command: + `cf runtime uninstall --git-token --silent` + where: + `--git-token` is a valid runtime token with the `repo` and `admin-repo.hook` scopes. + +**CLI wizard uninstall** + +1. In the Codefresh UI, make sure you are in [GitOps Runtimes](https://g.codefresh.io/2.0/account-settings/runtimes){:target="\_blank"}. +1. Switch to either the **List View** or to the **Topology View**. +1. **List view**: On the top-right, select the three dots and then select **Uninstall**. + + {% include + image.html + lightbox="true" + file="/images/runtime/uninstall-location.png" + url="/images/runtime/uninstall-location.png" + alt="List View: Uninstall runtime option" + caption="List View: Uninstall runtime option" + max-width="30%" +%} + +**Topology view**: Select the Runtime node, and from the panel, select the three dots and then select **Uninstall Runtime**. + {% include + image.html + lightbox="true" + file="/images/runtime/runtime-topology-uninstall.png" + url="/images/runtime/runtime-topology-uninstall.png" + alt="Topology View: Uninstall runtime option" + caption="Topology View: Uninstall runtime option" + max-width="30%" +%} + +{:start="4"} + +1. If you already have the latest version of the Codefresh CLI, in the Uninstall Codefresh Runtime panel, copy the uninstall command. + + {% include + image.html + lightbox="true" + file="/images/runtime/uninstall.png" + url="/images/runtime/uninstall.png" + alt="Uninstall Codefresh runtime" + caption="Uninstall Codefresh runtime" + max-width="40%" +%} + +{:start="5"} + +1. In your terminal, paste the command, and update the Git token value. +1. Select the Kube context from which to uninstall the Runtime, and then confirm the uninstall. +1. If you get errors, run the uninstall command again, with the `--force` flag. + + + +### Update Git tokens for Runtimes + +Provisioned Runtimes require valid Git tokens at all times to authenticate Git actions by you as a user. +>These tokens are specific to the user, and the same can be used for multiple runtimes. + +There are two different situations when you need to update Git tokens: +* Update invalid, revoked, or expired tokens: Codefresh automatically flags Runtimes with such tokens. It is mandatory to update the Git tokens to continue working with the platform. +* Update valid tokens: Optional. You may want to update Git tokens, even valid ones, by deleting the existing token and replacing it with a new token. + +The methods for updating any Git token are the same regardless of the reason for the update: +* OAuth2 authorization, if your admin has registered an OAuth Application for Codefresh +* Git access token authentication, by generating a personal access token in your Git provider account with the correct scopes + +**Before you begin** +* To authenticate through a Git access token, make sure your token is valid and has [the required scopes]({{site.baseurl}}/docs/reference/git-tokens) + +**How to** +1. Do one of the following: + * If you see a notification in the Codefresh UI about invalid Runtime tokens, click **[Update Token]**. + The Runtimes page shows Runtimes with invalid tokens prefixed by the key icon. Mouse over shows invalid token. + * To update an existing token, go to [GitOps Runtimes](https://g.codefresh.io/2.0/account-settings/runtimes){:target="\_blank"}. +1. Select the Runtime for which to update the Git token. +1. From the context menu with the additional actions at the top-right, select **Update Git Runtime token**. + + {% include + image.html + lightbox="true" + file="/images/runtime/update-git-runtime-token.png" + url="/images/runtime/update-git-runtime-token.png" + alt="Update Git runtime token option" + caption="Update Git runtime token option" + max-width="40%" +%} + +{:start="4"} +1. Do one of the following: + * If your admin has set up OAuth access, click **Authorize Access to Git Provider**. Go to _step 5_. + * Alternatively, authenticate with an access token from your Git provider. Go to _step 6_. + +{:start="5"} +1. For OAuth2 authorization: + > If the application is not registered, you get an error. Contact your admin for help. + * Enter your credentials, and select **Sign In**. + * If required, as for example if two-factor authentication is configured, complete the verification. + + {% include + image.html + lightbox="true" + file="/images/administration/user-settings/oauth-user-authentication.png" + url="/images/administration/user-settings/oauth-user-authentication.png" + alt="Authorizing access with OAuth2" + caption="Authorizing access with OAuth2" + max-width="30%" + %} + +{:start="6"} +1. For Git token authentication, expand **Advanced authorization options**, and then paste the generated token in the **Git runtime token** field. + +1. Click **Update Token**. + +## Monitoring GitOps Runtimes +* [View/download logs to troubleshoot Runtimes](#viewdownload-logs-to-troubleshoot-runtimes) +* [(Hybrid GitOps) Restoring provisioned Runtimes](#hybrid-gitops-restoring-provisioned-runtimes) +* [(Hybrid GitOps) Configure browser to allow insecure Runtimes](#hybrid-gitops-configure-browser-to-allow-insecure-runtimes) +* [(Hybrid GitOps) View notifications in Activity Log](#hybrid-gitops-view-notifications-in-activity-log) +* [(Hybrid GitOps) Troubleshoot health and sync errors for Runtimes](#hybrid-gitops-troubleshoot-health-and-sync-errors-for-runtimes) + +### View/download logs to troubleshoot Runtimes +Logs are available for completed Runtimes, both for the Runtime and for individual Runtime components. Download log files for offline viewing and analysis, or view online logs for a Runtime component, and download if needed for offline analysis. Online logs support free-text search, search-result navigation, and line-wrap for enhanced readability. + +Log files include events from the date of the application launch, with the newest events listed first. + +{::nomarkdown} +
+{:/} + +#### Download logs for Runtimes +Download the log file for a Runtime. The Runtime log is downloaded as a `.tar.gz` file, which contains the individual log files for each runtime component. + +1. In the Codefresh UI, go to [GitOps Runtimes](https://g.codefresh.io/2.0/account-settings/runtimes){:target="\_blank"}. +1. If needed, switch to **List View**, and then select the runtime for which to download logs. +1. From the context menu, select **Download All Logs**. + The log file is downloaded to the Downloads folder or the folder designated for downloads, with the filename, `.tar.gz`. For example, `codefreshv2-production2.tar.gz`. + + + {% include + image.html + lightbox="true" + file="/images/runtime/runtime-logs-download-all.png" + url="/images/runtime/runtime-logs-download-all.png" + alt="Download logs for selected runtime" + caption="Download logs for selected runtime" + max-width="40%" +%} + + +{:start="4"} +1. To view the log files of the individual components, unzip the file. + Here is an example of the folder with the individual logs. + + {% include + image.html + lightbox="true" + file="/images/runtime/runtime-logs-folder-view.png" + url="/images/runtime/runtime-logs-folder-view.png" + alt="Individual log files in folder" + caption="Individual log files in folder" + max-width="50%" +%} + +{:start="5"} +1. Open a log file with the text editor of your choice. + +{::nomarkdown} +
+{:/} + +#### View/download logs for Runtime components +View online logs for any Runtime component, and if needed, download the log file for offline viewing and analysis. + +Online logs show up to 1000 of the most recent events (lines), updated in real time. Downloaded logs include all the events, from the application launch to the date and time of download. + +1. In the Codefresh UI, go to [GitOps Runtimes](https://g.codefresh.io/2.0/account-settings/runtimes){:target="\_blank"}. +1. If needed, switch to **List View**, and then select the Runtime. +1. Select the Runtime component and then select **View Logs**. + + {% include + image.html + lightbox="true" + file="/images/runtime/runtime-logs-view-component.png" + url="/images/runtime/runtime-logs-view-component.png" + alt="View log option for individual runtime component" + caption="View log option for individual runtime component" + max-width="40%" +%} + + +{:start="4"} +1. Do the following: + * Search by free-text for any string, and click the next and previous buttons to navigate between the search results. + * To switch on line-wrap for readability, click **Wrap**. + + {% include + image.html + lightbox="true" + file="/images/runtime/runtime-logs-screen-view.png" + url="/images/runtime/runtime-logs-screen-view.png" + alt="Runtime component log example" + caption="Runtime component log example" + max-width="50%" +%} + +{:start="5"} +1. To download the log, click **Download**. + The file is downloaded as `.log`. + +### (Hybrid GitOps) Restoring provisioned Runtimes + +In case of cluster failure, restore the provisioned Hybrid Runtime from the existing runtime installation repository. +For partial or complete cluster failures, you can restore the Runtime to either the failed cluster or to a different cluster. +Restoring the provisioned Runtime reinstalls it, leveraging the resources in the existing Runtime repo. + +Restoring the runtime: +* Applies `argo-cd` from the installation manifests in your repo to your cluster +* Associates `argo-cd` with the existing installation repo +* Applies the Runtime and `argo-cd` secrets to the cluster +* Updates the Runtime config map (` .yaml` in the `bootstrap` directory) with the new cluster configuration for these fields: + `cluster` + `ingressClassName` + `ingressController` + `ingressHost` + +{::nomarkdown} +
+{:/} + +#### Restore a Hybrid Runtime +Reinstall the Hybrid Runtime from the existing installation repository to restore it to the same or a different cluster. + +**Before you begin** + +* Have the following information handy: + > All values must be the identical to the Runtime to be restored. + * Runtime name + * Repository URL + * Codefresh context + * Kube context: Required if you are restoring to the same cluster + +**How to** + +1. Run: + `cf runtime install --from-repo` +1. Provide the relevant values when prompted. +1. If you are performing the runtime recovery in a different cluster, verify the ingress resource configuration for `app-proxy`, `workflows`, and `default-git-source`. + If the health status remains as `Progressing`, do the following: + + * In the Runtime installation repo, check if the `ingress.yaml` files for the `app-proxy` and `workflows` are configured with the correct `host` and `ingressClassName`: + + `apps/app-proxy/overlays//ingress.yaml` + `apps/workflows/overlays/ /ingress.yaml` + + * In the Git Source repository, check the `host` and `ingressClassName` in `cdp-default-git-source.ingress.yaml`: + + `resources_ /cdp-default-git-source.ingress.yaml` + + See the [example](#ingress-example) below. + +{:start="4"} +1. If you have managed clusters registered to the hybrid runtime you are restoring, reconnect them. + Run the command and follow the instructions in the wizard: + `cf cluster add` + +1. Verify that you have a registered Git integration: + `cf integration git list --runtime ` + +1. If needed, create a new Git integration: + `cf integration git add default --runtime --provider github --api-url https://api.github.com` + +{::nomarkdown} +
+{:/} + +#### Ingress example +This is an example of the `ingress.yaml` for `workflows`. + + ```yaml +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + annotations: + ingress.kubernetes.io/protocol: https + ingress.kubernetes.io/rewrite-target: /$2 + nginx.ingress.kubernetes.io/backend-protocol: https + nginx.ingress.kubernetes.io/rewrite-target: /$2 + creationTimestamp: null + name: runtime-name-workflows-ingress + namespace: runtime-name +spec: + ingressClassName: nginx + rules: + - host: your-ingress-host.com + http: + paths: + - backend: + service: + name: argo-server + port: + number: 2746 + path: /workflows(/|$)(.*) + pathType: ImplementationSpecific +status: + loadBalancer: {} +``` + + +### (Hybrid GitOps) Configure browser to allow insecure Runtimes + +If at least one of your Hybrid Runtimes was installed in insecure mode (without an SSL certificate for the ingress controller from a CA), the UI alerts you that _At least one runtime was installed in insecure mode_. +{% include + image.html + lightbox="true" + file="/images/runtime/runtime-insecure-alert.png" + url="/images/runtime/runtime-insecure-alert.png" + alt="Insecure runtime installation alert" + caption="Insecure runtime installation alert" + max-width="100%" +%} + +All you need to do is to configure the browser to trust the URL and receive content. + +1. Select **View Runtimes** to the right of the alert. + You are taken to the Runtimes page, where you can see insecure Runtimes tagged as **Allow Insecure**. + {% include + image.html + lightbox="true" + file="/images/runtime/runtime-insecure-steps.png" + url="/images/runtime/runtime-insecure-steps.png" + alt="Insecure runtimes in Runtime page" + caption="Insecure runtimes in Runtime page" + max-width="40%" +%} +{:start="2"} +1. For _every_ insecure Runtime, select **Allow Insecure**, and when the browser prompts you to allow access, do as relevant: + +* Chrome: Click **Advanced** and then **Proceed to site**. +* Firefox: Click **Advanced** and then **Accept the risk and continue**. +* Safari: Click **Show Certificate**, and then select **Always allow content from site**. +* Edge: Click **Advanced**, and then select **Continue to site(unsafe)**. + +### (Hybrid GitOps) View notifications in Activity Log + +The Activity Log is a quick way to monitor notifications for Runtime events such as upgrades. A pull-down panel in the Codefresh toolbar, the Activity Log shows ongoing, success, and error notifications, sorted by date, starting with today's date. + +1. In the Codefresh UI, on the top-right of the toolbar, select  **Activity Log**. +1. To see notifications for provisioned Runtimes, filter by **Runtime**. + + {% include image.html + lightbox="true" + file="/images/runtime/runtime-activity-log.png" + url="/images/runtime/runtime-activity-log.png" + alt="Activity Log filtered by Runtime events" + caption="Activity Log filtered by Runtime events" + max-width="30%" + %} + +{:start="3"} + +1. To see more information on an error, select the **+** sign. + +### (Hybrid GitOps) Troubleshoot health and sync errors for Runtimes +The  icon with the Runtime in red indicates either health or sync errors. + +**Health errors** +Health errors are generated by Argo CD and by Codefresh for Runtime components. + +**Sync errors** +Runtimes with sync errors display an **Out of sync** status in Sync Status column. They are related to discrepancies between the desired and actual state of a Runtime component or one of the Git sources associated with the Runtime. + +**View errors** +For both views, select the Runtime, and then select **Errors Detected**. +Here is an example of health errors for a Runtime. + + {% include image.html + lightbox="true" + file="/images/runtime/runtime-health-sync-errors.png" + url="/images/runtime/runtime-health-sync-errors.png" + alt="Health errors for runtime example" + caption="Health errors for runtime example" + max-width="30%" + %} + + +### Related articles +[Add Git Sources to GitOps Runtimes]({{site.baseurl}}/docs/installation/git-sources/) +[Add external clusters to GitOps Runtimes]({{site.baseurl}}/docs/installation/managed-cluster/) +[Shared configuration repo for GitOps Runtimes]({{site.baseurl}}/docs/reference/shared-configuration) + + diff --git a/_docs/installation/runtime-architecture.md b/_docs/installation/runtime-architecture.md new file mode 100644 index 00000000..f31a7415 --- /dev/null +++ b/_docs/installation/runtime-architecture.md @@ -0,0 +1,240 @@ +--- +title: "Runtime architectures" +description: "" +group: installation +toc: true +--- + +Overview TBD + +## Codefresh CI/CD architecture + +The most important components are the following: + +**Codefresh VPC:** All internal Codefresh services run in the VPC (analyzed in the next section). Codefresh uses Mongo and PostgreSQL to store user and authentication information. + +**Pipeline execution environment**: The Codefresh engine component is responsible for taking pipeline definitions and running them in managed Kubernetes clusters by automatically launching the Docker containers that each pipeline needs for its steps. + +**External actors**. Codefresh offers a [public API]({{site.baseurl}}/docs/integrations/ci-integrations/codefresh-api/) that is consumed both by the Web user interface and the [Codefresh CLI](https://codefresh-io.github.io/cli/){:target="\_blank"}. The API is also available for any custom integration with external tools or services. + +### CI/CD topology + +If we zoom into Codefresh Services for CI/CD, we will see the following: + +{% include image.html + lightbox="true" + file="/images/administration/installation/topology-new.png" + url="/images/administration/installation/topology-new.png" + alt="Topology diagram" + caption="Topology diagram (click to enlarge)" + max-width="100%" + %} + +### CI/CD core components + +{: .table .table-bordered .table-hover} +|Category | Component | Function | +| -------------- | ----------| ----------| +| Core | **pipeline-manager**| Manages all CRUD operations for CI pipelines.| +| | **cfsign** | Signs server TLS certificates for docker daemons, and generates client TLS certificates for hybrid pipelines. | +| | **cf-api** | Central back-end component that functions as an API gateway for other services, and handles authentication/authorization. | +| | **context-manager**| Manages the authentications/configurations used by Codefresh CI/CD and by the Codefresh engine. | +| | **runtime-environment-manager**| Manages the different runtime environments for CI pipelines. The runtime environment for CI/CD SaaS is fully managed by Codefresh. For CI/CD Hybrid, customers can add their own runtime environments using private Kubernetes clusters. | +| Trigger | **hermes**| Controls CI pipeline trigger management. See [triggers]({{site.baseurl}}/docs/pipelines/triggers/). | +| | **nomios**| Enables triggers from Docker Hub when a new image/tag is pushed.See [Triggers from Docker Hub]({{site.baseurl}}/docs/pipelines/triggers/dockerhub-triggers/). | +| | **cronus**| Enables defining Cron triggers for CI pipelines. See [Cron triggers]({{site.baseurl}}/docs/pipelines/triggers/cron-triggers/).| +| Log | **cf-broadcaster**| Stores build logs from CI pipelines. The UI and CLI stream logs by accessing the **cf-broadcaster** through a web socket. | +| Kubernetes | **cluster-providers** | Provides an interface to define cluster contexts to connect Kubernetes clusters in CI/CD installation environments. | +| | **helm-repo-manager** | Manages the Helm charts for CI/CD installation environments through the Helm repository admin API and ChartMuseum proxy. See [Helm charts in Codefresh]({{site.baseurl}}/docs/deployments/helm/managed-helm-repository/). | +| | **k8s-monitor** | The agent installed on every Kubernetes cluster, providing information for the Kubernetes dashboards. See [Kubernetes dashboards]({{site.baseurl}}/docs/deployments/kubernetes/manage-kubernetes/). | +| |**charts-manager** | Models the Helm chart view in Codefresh. See [Helm chart view]({{site.baseurl}}/docs/deployments/helm/helm-releases-management/). | +| | **kube-integration** | Provides an interface to retrieve required information from a Kubernetes cluster, can be run either as an http server or an NPM module. | +| | **tasker-kubernetes** | Provides cache storage for Kubernetes dashboards. See [Kubernetes dashboards]({{site.baseurl}}/docs/deployments/kubernetes/manage-kubernetes/). | + + +## Codefresh GitOps Platform architecture + +The diagram shows a high-level view of the Codefresh GitOps installation environment, and its core components, the Codefresh Control Plane, the Codefresh Runtime, and the Codefresh Clients. + +{% include +image.html +lightbox="true" +file="/images/getting-started/architecture/arch-codefresh-simple.png" +url="/images/getting-started/architecture/arch-codefresh-simple.png" +alt="Codefresh GitOps Platform architecture" +caption="Codefresh GitOps Platform architecture" +max-width="100%" +%} + +{::nomarkdown} +
+{:/} + +### Codefresh GitOps Control Plane +The Codefresh Control Plane is the SaaS component in the platform. External to the enterprise firewall, it does not have direct communication with the Codefresh Runtime, Codefresh Clients, or the customer's organizational systems. The Codefresh Runtime and the Codefresh Clients communicate with the Codefresh Control Plane to retrieve the required information. + + +{::nomarkdown} +
+{:/} + +### Codefresh GitOps Runtime +The Codefresh Runtime is installed on a Kubernetes cluster, and houses the enterprise distribution of the Codefresh Application Proxy and the Argo Project. +Depending on the type of GitOps installation, the Codefresh Runtime is installed either in the Codefresh platform (Hosted GitOps), or in the customer environment (Hybrid GitOps). Read more in [Codefresh GitOps Runtime architecture](#codefresh-gitops-runtime-architecture). + + +{::nomarkdown} +
+{:/} + +### Codefresh GitOps Clients + +Codefresh Clients include the Codefresh UI and the Codefresh CLI. +The Codefresh UI provides a unified, enterprise-wide view of deployments (runtimes and clusters), and CI/CD operations (Delivery Pipelines, workflows, and deployments) in the same location. +The Codefresh CLI includes commands to install hybrid runtimes, add external clusters, and manage runtimes and clusters. + +### Codefresh GitOps Runtime architecture +The sections that follow show detailed views of the GitOps Runtime architecture for the different installation options, and descriptions of the GitOps Runtime components. + +* [Hosted GitOps runtime architecture](#hosted-gitops-runtime-architecture) + For Hosted GitOps, the GitOps Runtime is installed on a _Codefresh-managed cluster_ in the Codefresh platform. +* Hybrid GitOps runtime architecture: + For Hybrid GitOps, the GitOps Runtime is installed on a _customer-managed cluster_ in the customer environment. The Hybrid GitOps Runtime can be tunnel- or ingress-based: + * [Tunnel-based](#tunnel-based-hybrid-gitops-runtime-architecture) + * [Ingress-based](#ingress-based-hybrid-gitops-runtime-architecture) +* GitOps Runtime components + * [Application Proxy](#application-proxy) + * [Argo Project](#argo-project) + * [Request Routing Service](#request-routing-service) + * [Tunnel Server](#tunnel-server) + * [Tunnel Client](#tunnel-client) + + +#### Hosted GitOps runtime architecture +In the hosted environment, the Codefresh Runtime is installed on a K8s cluster managed by Codefresh. + +{% include + image.html + lightbox="true" + file="/images/getting-started/architecture/arch-hosted.png" + url="/images/getting-started/architecture/arch-hosted.png" + alt="Hosted runtime architecture" + caption="Hosted runtime architecture" + max-width="100%" +%} + +#### Tunnel-based Hybrid GitOps runtime architecture +Tunnel-based Hybrid GitOps runtimes use tunneling instead of ingress controllers to control communication between the GitOps Runtime in the customer cluster and the Codefresh GitOps Platform. Tunnel-based runtimes are optimal when the cluster with the GitOps Runtime is not exposed to the internet. + +{% include + image.html + lightbox="true" + file="/images/getting-started/architecture/arch-hybrid-ingressless.png" + url="/images/getting-started/architecture/arch-hybrid-ingressless.png" + alt="Tunnel-based hybrid runtime architecture" + caption="Tunnel-based hybrid runtime architecture" + max-width="100%" +%} + + +#### Ingress-based Hybrid GitOps runtime architecture +Ingress-based runtimes use ingress controllers to control communication between the GitOps Runtime in the customer cluster and the Codefresh GitOps Platform. Ingress-based runtimes are optimal when the cluster with the GitOps Runtime is exposed to the internet. + + + +{% include + image.html + lightbox="true" + file="/images/getting-started/architecture/arch-hybrid-ingress.png" + url="/images/getting-started/architecture/arch-hybrid-ingress.png" + alt="Ingress-based hybrid runtime architecture" + caption="Ingress-based hybrid runtime architecture" + max-width="100%" +%} + + +#### Application Proxy +The GitOps Application Proxy (App-Proxy) functions as the Codefresh agent, and is deployed as a service in the GitOps Runtime. + +For tunnel-based Hybrid GitOps Runtimes, the Tunnel Client forwards the incoming traffic from the Tunnel Server using the Request Routing Service to the GitOps App-Proxy. +For Hybrid GitOps Runtimes with ingress, the App-Proxy is the single point-of-contact between the GitOps Runtime, and the GitOps Clients, the GitOps Platform, and any organizational systems in the customer environment. + + +The GitOps App-Proxy: +* Accepts and serves requests from GitOps Clients either via the UI or CLI +* Retrieves a list of Git repositories for visualization in the Client interfaces +* Retrieves permissions from the GitOps Control Plane to authenticate and authorize users for the required operations. +* Implements commits for GitOps-controlled entities, such as Delivery Pipelines and other CI resources +* Implements state-change operations for non-GitOps controlled entities, such as terminating Argo Workflows + +{::nomarkdown} +
+{:/} + +#### Argo Project + +The Argo Project includes: +* Argo CD for declarative continuous deployment +* Argo Rollouts for progressive delivery +* Argo Workflows as the workflow engine +* Argo Events for event-driven workflow automation framework + + +{::nomarkdown} +
+{:/} + +#### Request Routing Service +The Request Routing Service is installed on the same cluster as the GitOps Runtime in the customer environment. +It receives requests from the the Tunnel Client (tunnel-based) or the ingress controller (ingress-based), and forwards the request URLs to the Application Proxy, and webhooks directly to the Event Sources. + +>Important: + The Request Routing Service is available from runtime version 0.0.543 and higher. + Older runtime versions are not affected as there is complete backward compatibility, and the ingress controller continues to route incoming requests. + +#### Tunnel Server +Applies only to _tunnel-based_ Hybrid GitOps Runtimes. +The Codefresh Tunnel Server is installed in the Codefresh platform. It communicates with the enterprise cluster located behind a NAT or firewall. + +The Tunnel Server: +* Forwards traffic from Codefresh Clients to the client (customer) cluster. +* Manages the lifecycle of the Tunnel Client. +* Authenticates requests from the Tunnel Client to open tunneling connections. + +{::nomarkdown} +
+{:/} + +#### Tunnel Client +Applies only to _tunnel-based_ Hybrid GitOps Runtimes. + +Installed on the same cluster as the Hybrid GitOps Runtime, the Tunnel Client establishes the tunneling connection to the Tunnel Server via the WebSocket Secure (WSS) protocol. +A single Hybrid GitOps Runtime can have a single Tunnel Client. + +The Tunnel Client: +* Initiates the connection with the Tunnel Server. +* Forwards the incoming traffic from the Tunnel Server through the Request Routing Service to App-Proxy, and other services. + +{::nomarkdown} +
+{:/} + + +#### Customer environment +The customer environment that communicates with the GitOps Runtime and the GitOps Platform, generally includes: +* Ingress controller for ingress hybrid runtimes + The ingress controller is configured on the same Kubernetes cluster as the GitOps Runtime, and implements the ingress traffic rules for the GitOps Runtime. + See [Ingress controller requirements]({{site.baseurl}}/docs/installation/requirements/#ingress-controller). +* Managed clusters + Managed clusters are external clusters registered to provisioned Hosted or Hybrid GitOps runtimes for application deployment. + Hosted GitOps requires you to connect at least one external K8s cluster as part of setting up the Hosted GitOps environment. + Hybrid GitOps allow you to add external clusters after provisioning the runtimes. + See [Add external clusters to runtimes]({{site.baseurl}}/docs/installation/managed-cluster/). +* Organizational systems + Organizational Systems include the customer's tracking, monitoring, notification, container registries, Git providers, and other systems. They can be entirely on-premises or in the public cloud. + Either the ingress controller (ingress hybrid environments), or the Tunnel Client (tunnel-based hybrid environments), forwards incoming events to the Codefresh Application Proxy. + + ## Related articles +[Codefresh pricing](https://codefresh.io/pricing/) +[Codefresh features](https://codefresh.io/features/) + \ No newline at end of file diff --git a/_docs/installation/upgrade-gitops-cli.md b/_docs/installation/upgrade-gitops-cli.md new file mode 100644 index 00000000..30e06096 --- /dev/null +++ b/_docs/installation/upgrade-gitops-cli.md @@ -0,0 +1,87 @@ +--- +title: "Download/upgrade Codefresh CLI" +description: "Have the latest version of the Codefresh CLI for GitOps runtimes" +group: installation +toc: true +--- + +You need the Codefresh CLI to install Hybrid GitOps Runtimes, and have access to all the newest features. +For the initial download, you need to generate an API key and create the API authentication context, which you do from the UI. +When newer versions are available, the CLI automatically notifies you through a banner. You can use the existing API credentials for the upgrade. + + +## GitOps CLI installation modes +The table lists the modes available to install the Codefresh CLI. + +{: .table .table-bordered .table-hover} +| Install mode | OS | Commands | +| -------------- | ----------| ----------| +| `curl` | MacOS-x64 | `curl -L --output - https://github.com/codefresh-io/cli-v2/releases/latest/download/cf-darwin-amd64.tar.gz | tar zx && mv ./cf-darwin-amd64 /usr/local/bin/cf && cf version`| +| | MacOS-m1 |`curl -L --output - https://github.com/codefresh-io/cli-v2/releases/latest/download/cf-darwin-arm64.tar.gz | tar zx && mv ./cf-darwin-arm64 /usr/local/bin/cf && cf version` | +| | Linux - X64 |`curl -L --output - https://github.com/codefresh-io/cli-v2/releases/latest/download/cf-linux-amd64.tar.gz | tar zx && mv ./cf-linux-amd64 /usr/local/bin/cf && cf version` | +| | Linux - ARM | `curl -L --output - https://github.com/codefresh-io/cli-v2/releases/latest/download/cf-linux-arm64.tar.gz | tar zx && mv ./cf-linux-arm64 /usr/local/bin/cf && cf version`| +| `brew` | N/A| `brew tap codefresh-io/cli && brew install cf2`|```` + +## Install the GitOps CLI +Install the Codefresh CLI using the option that best suits you: `curl`, `brew`, or standard download. +If you are not sure which OS to select for `curl`, simply select one, and Codefresh automatically identifies and selects the right OS for CLI installation. + +1. Do one of the following: + * For first-time installation, go to the Welcome page, select **+ Install Runtime**. + * If you have provisioned a GitOps Runtime, in the Codefresh UI, go to [GitOps Runtimes](https://g.codefresh.io/2.0/account-settings/runtimes){:target="\_blank"}, and select **+ Add Runtime**. +1. Install the Codefresh CLI: + * Select one of the installation modes. + * Generate the API key. + * Create the authentication context: + `cf config create-context codefresh --api-key` + + + {% include + image.html + lightbox="true" + file="/images/getting-started/quick-start/quick-start-download-cli.png" + url="/images/getting-started/quick-start/quick-start-download-cli.png" + alt="Download CLI to install runtime" + caption="Download CLI to install runtime" + max-width="30%" + %} + + +{::nomarkdown} + +{:/} + + +## Upgrade the GitOps CLI + +The Codefresh CLI automatically self-checks its version, and if a newer version is available, prints a banner with the notification. + + {% include + image.html + lightbox="true" + file="/images/runtime/cli-upgrade-banner.png" + url="/images/runtime/cli-upgrade-banner.png" + alt="Upgrade banner for Codefresh CLI" + caption="Upgrade banner for Codefresh CLI" + max-width="40%" + %} + + +You can upgrade to a specific version if you so require, or download the latest version to an output folder to upgrade at your convenience. + + +* Do any of the following: + * To upgrade to the latest version, run: + `cf upgrade` + * To upgrade to a specific version, even an older version, run: + `cf upgrade --version v ` + where: + ` ` is the version you want to upgrade to. + * To download the latest version to an output file, run: + `cf upgrade --version v -o ` + where: + * ` ` is the path to the destination file, for example, `/cli-download`. + +## Related articles +[Hosted GitOps Runtime setup]({{site.baseurl}}/docs/installation/hosted-runtime) +[Hybrid GitOps Runtime installation]({{site.baseurl}}/docs/installation/hybrid-gitops) diff --git a/_docs/reference/behind-the-firewall.md b/_docs/reference/behind-the-firewall.md new file mode 100644 index 00000000..b01ba138 --- /dev/null +++ b/_docs/reference/behind-the-firewall.md @@ -0,0 +1,248 @@ +--- +title: "Runner installation behind firewalls" +description: "Run Codefresh Pipelines in your own secure infrastructure" +group: installation +redirect_from: + - /docs/enterprise/behind-the-firewall/ +toc: true + +--- + +As described in [installation options]({{site.baseurl}}/docs/installation/installation-options/) Codefresh offers CI/CD and GitOps installation environments, each with its own installation options. +This articles focuses on the CI/CD Hybrid installation option with the Codefresh Runner and its advantages. + +## Running Codefresh CI/CD in secure environments + +Codefresh CI/CD has an on-premises installation in which the Codefresh CI/CD platform is installed on the customer's premises. While +this solution is very effective as far as security is concerned, it places a lot of overhead on the customer, as all updates +and improvements done in the platform must also be transferred to the customer premises. + +Hybrid CI/CD places a Codefresh Runner within the customer premises, and the UI (and management platform) stays in the Codefresh SaaS. + +Here is the overall architecture: + +{% include image.html + lightbox="true" + file="/images/administration/behind-the-firewall/architecture.png" + url="/images/administration/behind-the-firewall/architecture.png" + alt="Codefresh Hybrid CD/CD behind the firewall" + caption="Codefresh Hybrid CD/CD behind the firewall" + max-width="100%" + %} + +The advantages for this scenario are multi-fold. + +Regarding platform maintenance: + + 1. Codefresh is responsible for the heavy lifting for platform maintenance, instead of the customer. + 1. Updates to the UI, build engine, integrations etc., happen automatically, without any customer involvement. + 1. Actual builds run in the customer premises under fully controlled conditions. + 1. Codefresh Runner is fully automated. It handles volume claims and build scheduling on its own within the Kubernetes cluster it is placed. + +Regarding security of services: + + 1. Pipelines can run in behind-the-firewall clusters with internal services. + 1. Pipelines can use integrations (such as Docker registries) that are private and secure. + 1. Source code does not ever leave the customer premises. + +Regarding firewall security: + + 1. Uni-directional, outgoing communication between the Codefresh Runner and Codefresh CI/CD Platform. The Runner polls the Codefresh platform for jobs. + 1. Codefresh SaaS never connects to the customer network. No ports need to be open in the customer firewall for the runner to work. + 1. The Codefresh Runner is fully open-sourced, so its code can be scrutinized by any stakeholder. + + + +## Using secure services in your CI pipelines + +After installing the [Codefresh Runner]({{site.baseurl}}/docs/installation/codefresh-runner/) on your private Kubernetes cluster in your infrastructure, all CI pipelines in the private Kubernetes cluster have access to all other internal services that are network reachable. + +You can easily create CI pipelines that: + + * Use databases internal to the company + * Run integration tests against services internal to the company + * Launch [compositions]({{site.baseurl}}/docs/pipelines/steps/composition/) that communicate with other secure services + * Upload and download artifacts from a private artifact repository (e.g., Nexus or Artifactory) + * Deploy to any other cluster accessible in the secure network + * Create infrastructure such as machines, load balancers, auto-scaling groups etc. + + Any of these CI pipelines will work out the box without extra configuration. In all cases, + all data stays witin the private local network and does not exit the firewall. + + >Notice that [long-running compositions]({{site.baseurl}}/docs/pipelines/steps/composition/) (preview test environments) are not yet available via the Codefresh build runner. + + + +### Checking out code from a private GIT repository + +To check out code from your private Git repository, you need to connect first to Codefresh via [GIT integrations]({{site.baseurl}}/docs/integrations/git-providers/). However, once you define your GIT provider as *on premise* you also +need to mark it as *behind the firewall* as well: + +{% include image.html + lightbox="true" + file="/images/administration/behind-the-firewall/behind-the-firewall-toggle.png" + url="/images/administration/behind-the-firewall/behind-the-firewall-toggle.png" + alt="Behind the firewall toggle" + caption="Behind the firewall toggle" + max-width="100%" + %} + +Once you do that save your provider and make sure that it has the correct tags. The name you used for the git provider will also be used in the pipeline. You cannot "test the connection" because +the Codefresh SAAS doesn't have access to your on-premises GIT repository. + +{% include image.html + lightbox="true" + file="/images/administration/behind-the-firewall/behind-the-firewall-tag.png" + url="/images/administration/behind-the-firewall/behind-the-firewall-tag.png" + alt="Behind the firewall tags" + caption="Behind the firewall tags" + max-width="100%" + %} + +To check out code just use a [clone step]({{site.baseurl}}/docs/pipelines/steps/git-clone/) like any other clone operation. +The only thing to remember is that the GIT URL must be fully qualified. You need to [create a pipeline]({{site.baseurl}}/docs/pipelines/pipelines/#pipeline-creation-modes) on it its own from the *Pipelines* section of the left sidebar (instead of one adding a git repository to Codefresh) + + + +`YAML` +{% highlight yaml %} +{% raw %} +version: '1.0' +steps: + main_clone: + type: git-clone + description: Step description + repo: https://github-internal.example.com/my-username/my-app + git: my-internal-git-provider + BuildingDockerImage: + title: Building Docker Image + type: build + image_name: my-image + tag: '${{CF_BRANCH_TAG_NORMALIZED}}-${{CF_SHORT_REVISION}}' + dockerfile: Dockerfile +{% endraw %} +{% endhighlight %} + +Once you trigger the CI pipeline, the Codefresh builder will communicate with your private GIT instance and checks out code. + +>Note that currently there is a limitation on the location of the `codefresh.yml` file. Only the [inline mode]({{site.baseurl}}/docs/pipelines/pipelines/#writing-codefresh-yml-in-the-gui) is supported. Soon we will allow the loading of the pipeline from the Git repository itself. + +You can also use a [network proxy]({{site.baseurl}}/docs/pipelines/steps/git-clone/#using-git-behind-a-proxy) for the Git clone step. + +#### Adding triggers from private GIT repositories + + +In the previous section we have seen how a CI pipeline can check out code from an internal Git repository. We also need to set up a trigger, +so that every time a commit or any other supported event occurs, the Codefresh CI pipeline is triggered automatically. + +If you have installed the [optional app-proxy]({{site.baseurl}}/docs/installation/codefresh-runner/#optional-installation-of-the-app-proxy), adding a trigger can be done exactly like the SAAS version of Codefresh, using only the Codefresh UI. + +If you haven't installed the app-proxy, then adding a Git trigger is a two-step process: + +1. First we set up a webhook endpoint in Codefresh. +1. Then we create the webhook call in the side of the the GIT provider. + +> To support triggers based on PR (Pull Request) events, it is mandatory to install `app-proxy`. + +For the Codefresh side, follow the usual instructions for creating a [basic git trigger]({{site.baseurl}}/docs/configure-ci-cd-pipeline/triggers/git-triggers/). + +Once you select your GIT provider, you need to manually enter your username and repository that you wish to trigger the build. + +{% include image.html + lightbox="true" + file="/images/administration/behind-the-firewall/enter-repo-details.png" + url="/images/administration/behind-the-firewall/enter-repo-details.png" + alt="Entering repository details" + caption="Entering repository details" + max-width="60%" + %} + +All other details (git events, branch naming, monorepo pattern, etc.) are still the same as normal SAAS GIT providers. +Once that is done, Codefresh will show you the webhook endpoint along with a secret for triggering this pipeline. Note them down. + + +{% include image.html + lightbox="true" + file="/images/administration/behind-the-firewall/codefresh-webhook.png" + url="/images/administration/behind-the-firewall/codefresh-webhook.png" + alt="Codefresh webhook details" + caption="Codefresh webhook details" + max-width="60%" + %} + +This concludes the setup on the Codefresh side. The final step is create a webhook call on the side of your GIT provider. +The instructions are different per GIT provider: + +* [GitHub webhooks](https://developer.github.com/webhooks/) +* [GitLab webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) +* [Stash webhooks](https://confluence.atlassian.com/bitbucketserver/managing-webhooks-in-bitbucket-server-938025878.html) + +In all cases make sure that the payload is JSON, because this is what Codefresh expects. + +* For GitHub the events monitored should be `Pull requests` and `Pushes`. +* For GitLab the events monitored should be `Push events`,`Tag push events` and `Merge request events`. + +After the setup is finished, the Codefresh pipeline will be executed every time a git event happens. + +### Accessing an internal docker registry + +To access an internal registry just follow the instructions for [adding registries]({{site.baseurl}}/docs/docker-registries/external-docker-registries/) . Like GIT repositories +you need to mark the Docker registry as *Behind the firewall*. + +Once that is done, use the [push step]({{site.baseurl}}/docs/codefresh-yaml/steps/push/) as usual with the name you gave to the registry during the integration setup. + + +`YAML` +{% highlight yaml %} +{% raw %} +version: '1.0' +steps: + gitClone: + type: git-clone + description: Step description + repo: https://github-internal.example.com/my-username/my-app + git: my-internal-git-repo + BuildingDockerImage: + title: Building Docker Image + type: build + image_name: my-image + dockerfile: Dockerfile + PushingDockerImage: + title: Pushing a docker image + type: push + candidate: '${{BuildingDockerImage}}' + tag: '${{CF_BRANCH}}' + registry: my-internal-docker-registry +{% endraw %} +{% endhighlight %} + + +### Deploying to an internal Kubernetes cluster + +To connect a cluster that is behind the firewall follow the [connecting cluster guide]({{site.baseurl}}/docs/deploy-to-kubernetes/add-kubernetes-cluster/), paying attention to the following two points: + +1. Your cluster should be added as a [Custom provider]({{site.baseurl}}/docs/deploy-to-kubernetes/add-kubernetes-cluster/#adding-any-other-cluster-type-not-dependent-on-any-provider) +1. You need to mark the cluster as internal by using the toggle switch. + + + + +{% include image.html + lightbox="true" + file="/images/administration/behind-the-firewall/cluster-behind-firewall.png" + url="/images/administration/behind-the-firewall/cluster-behind-firewall.png" + alt="Marking a Kubernetes cluster as internal" + caption="Marking a Kubernetes cluster as internal" + max-width="60%" + %} + +The cluster where the runner works on should have network connectivity with the cluster you wish to deploy to. + +>Notice that the service account used in the cluster configuration is completely independent from the privileges granted to the Codefresh build runner. The privileges needed by the runner are only used to launch Codefresh pipelines within your cluster. The Service account used in the "custom provider" setting should have the needed privileges for deployment. + +Once your cluster is connected you can use any of the familiar deployment methods such as the [dedicated deploy step]({{site.baseurl}}/docs/deploy-to-kubernetes/deployment-options-to-kubernetes/) or [custom kubectl commands]({{site.baseurl}}/docs/deploy-to-kubernetes/custom-kubectl-commands/). + +## Related articles +[Codefresh installation options]({{site.baseurl}}/docs/installation/installation-options/) +[Google marketplace integration]({{site.baseurl}}/docs/integrations/ci-integrations/google-marketplace/) +[Managing your Kubernetes cluster]({{site.baseurl}}/docs/deployments/kubernetes/manage-kubernetes/) diff --git a/_docs/runtime/download-runtime-logs.md b/_docs/runtime/download-runtime-logs.md deleted file mode 100644 index ca6cf8ff..00000000 --- a/_docs/runtime/download-runtime-logs.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: "View/download runtime logs" -description: "" -group: runtime -toc: true ---- - -Logs are available for completed runtimes, both for the runtime and for individual runtime components. Download runtime log files for offline viewing and analysis, or view online logs for a runtime component, and download if needed for offline analysis. Online logs support free-text search, search-result navigation, and line-warp for enhanced readability. - -Log files include events from the date of the application launch, with the newest events listed first. - - -### Download logs for runtimes -Download the log file for a runtime. The runtime log is downloaded as a `.tar.gz` file, which contains the individual log files for each runtime component. - -1. In the Codefresh UI, go to [Runtimes](https://g.codefresh.io/2.0/account-settings/runtimes){:target="\_blank"}. -1. If needed, switch to **List View**, and then select the runtime for which to download logs. -1. From the list of **Additional Actions**, select **Download All Logs**. - The log file is downloaded to the Downloads folder or the folder designated for downloads, with the filename, ` .tar.gz`. For example, `codefreshv2-production2.tar.gz`. - - - {% include - image.html - lightbox="true" - file="/images/runtime/runtime-logs-download-all.png" - url="/images/runtime/runtime-logs-download-all.png" - alt="Download logs for selected runtime" - caption="Download logs for selected runtime" - max-width="40%" -%} - - -{:start="4"} -1. To view the log files of the individual components, unzip the file. - Here is an example of the folder with the individual logs. - - {% include - image.html - lightbox="true" - file="/images/runtime/runtime-logs-folder-view.png" - url="/images/runtime/runtime-logs-folder-view.png" - alt="Individual log files in folder" - caption="Individual log files in folder" - max-width="50%" -%} - -{:start="5"} -1. Open a log file with the text editor of your choice. - - -### View/download logs for runtime components -View online logs for any runtime component, and if needed, download the log file for offline viewing and analysis. - -Online logs show up to 1000 of the most recent events (lines), updated in real time. Downloaded logs include all the events from the application launch to the date and time of download. - -1. In the Codefresh UI, go to [Runtimes](https://g.codefresh.io/2.0/account-settings/runtimes){:target="\_blank"}. -1. If needed, switch to **List View**, and then select the runtime. -1. Select the runtime component and then select **View Logs**. - - {% include - image.html - lightbox="true" - file="/images/runtime/runtime-logs-view-component.png" - url="/images/runtime/runtime-logs-view-component.png" - alt="View log option for individual runtime component" - caption="View log option for individual runtime component" - max-width="40%" -%} - - -{:start="4"} -1. Do the following: - * Search by free-text for any string, and click the next and previous buttons to navigate between the search results. - * To switch on line-wrap for readability, click **Wrap**. - - {% include - image.html - lightbox="true" - file="/images/runtime/runtime-logs-screen-view.png" - url="/images/runtime/runtime-logs-screen-view.png" - alt="Runtime component log example" - caption="Runtime component log example" - max-width="50%" -%} - -{:start="5"} -1. To download the log, click **Download**. - The file is downloaded as ` .log`. - -### Related information -[Manage Git Sources]({{site.baseurl}}/docs/runtime/git-sources/#viewdownload-logs-for-a-git-source) \ No newline at end of file diff --git a/_docs/runtime/installation-options.md b/_docs/runtime/installation-options.md deleted file mode 100644 index e75e2058..00000000 --- a/_docs/runtime/installation-options.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: "Installation environments" -description: "" -group: runtime -toc: true ---- - -Codefresh supports two installation environments: - - -* **Hosted** environments (Beta), with Argo CD installed in the Codefresh cluster. - The runtime is installed and provisioned in a Codefresh cluster, and managed by Codefresh. - Hosted enviroments are full-cloud environments, where all updates and improvements are managed by Codefresh, with zero-maintenance overhead for you as the customer. Currently, you can add one hosted runtime per account. - For the architecture illustration, see [Hosted runtime architecture]({{site.baseurl}}/docs/getting-started/architecture/#hosted-runtime-architecture). - - -{% include - image.html - lightbox="true" - file="/images/runtime/intro-hosted-hosted-initial-view.png" - url="/images/runtime/intro-hosted-hosted-initial-view.png" - alt="Hosted runtime setup" - caption="Hosted runtime setup" - max-width="80%" -%} - - For more information on how to set up the hosted environment, including provisioning hosted runtimes, see [Set up a hosted (Hosted GitOps) environment]({{site.baseurl}}/docs/runtime/hosted-runtime/). - -* **Hybrid** environments, with Argo CD installed in the customer's cluster. - The runtime is installed in the customer's cluster, and managed by the customer. - Hybrid environments are optimal for organizations that want to manage CI/CD operations within their premises, or have other security constraints. Hybrid installations strike the perfect balance between security, flexibility, and ease of use. Codefresh maintains and manages most aspects of the platform, apart from installing and upgrading runtimes which are managed by the customer. - - -{% include - image.html - lightbox="true" - file="/images/runtime/runtime-list-view.png" - url="/images/runtime/runtime-list-view.png" - alt="Runtime List View" - caption="Runtime List View" - max-width="70%" -%} - - For more information on hybrid environments, see [Hybrid runtime requirements]({{site.baseurl}}/docs/runtime/requirements/) and [Installling hybrid runtimes]({{site.baseurl}}/docs/runtime/installation/). - - - -#### Git provider repos -Codefresh Runtime creates three repositories in your organization's Git provider account: - -* Codefresh runtime installation repository -* Codefresh Git Sources -* Codefresh shared configuration repository - - - -### Hosted vs.Hybrid environments - -The table below highlights the main differences between hosted and hybrid environments. - -{: .table .table-bordered .table-hover} -| Functionality |Feature | Hosted | Hybrid | -| -------------- | -------------- |--------------- | --------------- | -| Runtime | Installation | Provisioned by Codefresh | Provisioned by customer | -| | Runtime cluster | Managed by Codefresh | Managed by customer | -| | Number per account | One runtime | Multiple runtimes | -| | External cluster | Managed by customer | Managed by customer | -| | Upgrade | Managed by Codefresh | Managed by customer | -| | Uninstall | Managed by customer | Managed by customer | -| Argo CD | | Codefresh cluster | Customer cluster | -| CI Ops | Delivery Pipelines |Not supported | Supported | -| |Workflows | Not supported | Supported | -| |Workflow Templates | Not supported | Supported | -| CD Ops |Applications | Supported | Supported | -| |Image enrichment | Supported | Supported | -| | Rollouts | Supported | Supported | -|Integrations | | Supported | Supported | -|Dashboards |Home Analytics | Hosted runtime and deployments|Runtimes, deployments, Delivery Pipelines | -| |DORA metrics | Supported |Supported | -| |Applications | Supported |Supported | - -### Related articles -[Architecture]({{site.baseurl}}/docs/getting-started/architecture/) -[Add Git Sources to runtimes]({{site.baseurl}}/docs/runtime/git-sources/) -[Shared configuration repository]({{site.baseurl}}/docs/reference/shared-configuration) - diff --git a/_docs/runtime/installation.md b/_docs/runtime/installation.md deleted file mode 100644 index 44012210..00000000 --- a/_docs/runtime/installation.md +++ /dev/null @@ -1,535 +0,0 @@ ---- -title: "Install hybrid runtimes" -description: "" -group: runtime -toc: true ---- - -If you have a hybrid environment, you can provision one or more hybrid runtimes in your Codefresh account. - -> If you have Hosted GitOps, to provision a hosted runtime, see [Provision a hosted runtime]({{site.baseurl}}/docs/runtime/hosted-runtime/#1-provision-hosted-runtime) in [Set up a hosted (Hosted GitOps) environment]({{site.baseurl}}/docs/runtime/hosted-runtime/). - -**Git providers and runtimes** -Your Codefresh account is always linked to a specific Git provider. This is the Git provider you select on installing the first runtime, either hybrid or hosted, in your Codefresh account. All the hybrid runtimes you install in the same account use the same Git provider. -If Bitbucker Server is your Git provider, you must also select the specific server instance to associate with the runtime. - ->To change the Git provider for your Codefresh account after installation, contact Codefresh support. - - -**Hybrid runtime** - The hybrid runtime comprises Argo CD components and Codefresh-specific components. The Argo CD components are derived from a fork of the Argo ecosystem, and do not correspond to the open-source versions available. - -There are two parts to installing a hybrid runtime: - -1. Installing the Codefresh CLI -2. Installing the hybrid runtime from the CLI, either through the CLI wizard or via silent installation through the installation flags. - The hybrid runtime is installed in a specific namespace on your cluster. You can install more runtimes on different clusters in your deployment. - Every hybrid runtime installation makes commits to three Git repos: - * Runtime install repo: The installation repo that manages the hybrid runtime itself with Argo CD. If the repo URL does not exist, it is automatically created during runtime installation. - * Git Source repo: Created automatically during runtime installation. The repo where you store manifests for pipelines and applications. See [Git Sources]({{site.baseurl}}/docs/runtime/git-sources). - * Shared configuration repo: Created for the first runtime in a user account. The repo stores configuration manifests for account-level resources and is shared with other runtimes in the same account. See [Shared configuration repository]({{site.baseurl}}/docs/reference/shared-configuration). - - -See also [Codefresh architecture]({{site.baseurl}}/docs/getting-started/architecture). - -{::nomarkdown} - -{:/} - -### Hybrid runtime installation flags -This section describes the required and optional flags to install a hybrid runtime. -For documentation purposes, the flags are grouped into: -* Runtime flags, relating to runtime, cluster, and namespace requirements -* Ingress controller flags, relating to ingress controller requirements -* Git provider flags -* Codefresh resource flags - -{::nomarkdown} - -{:/} - -#### Runtime flags - -**Runtime name** -Required. -The runtime name must start with a lower-case character, and can include up to 62 lower-case characters and numbers. -* CLI wizard: Add when prompted. -* Silent install: Add the `--runtime` flag and define the runtime name. - -**Namespace resource labels** -Optional. -The label of the namespace resource to which you are installing the hybrid runtime. Labels are required to identify the networks that need access during installation, as is the case when using services meshes such as Istio for example. - -* CLI wizard and Silent install: Add the `--namespace-labels` flag, and define the labels in `key=value` format. Separate multiple labels with `commas`. - -**Kube context** -Required. -The cluster defined as the default for `kubectl`. If you have more than one Kube context, the current context is selected by default. - -* CLI wizard: Select the Kube context from the list displayed. -* Silent install: Explicitly specify the Kube context with the `--context` flag. - -**Shared configuration repository** -The Git repository per runtime account with shared configuration manifests. -* CLI wizard and Silent install: Add the `--shared-config-repo` flag and define the path to the shared repo. - -{::nomarkdown} - -{:/} - -#### Ingress-less flags -These flags are required to install the runtime without an ingress controller. - -**Access mode** -Required. - -The access mode for ingress-less runtimes, the tunnel mode. - - -* CLI wizard and Silent install: Add the flag, `--access-mode`, and define `tunnel` as the value. - - -**IP allowlist** - -Optional. - -The allowed list of IPs from which to forward requests to the internal customer cluster for ingress-less runtime installations. The allowlist can include IPv4 and IPv6 addresses, with/without subnet and subnet masks. Multiple IPs must be separated by commas. - -When omitted, all incoming requests are authenticated regardless of the IPs from which they originated. - -* CLI wizard and Silent install: Add the `--ips-allow-list` flag, followed by the IP address, or list of comma-separated IPs to define more than one. For example, `--ips-allow-list 77.126.94.70/16,192.168.0.0` - -{::nomarkdown} - -{:/} - -#### Ingress controller flags - - -**Skip ingress** -Required, if you are using an unsupported ingress controller. -For unsupported ingress controllers, bypass installing ingress resources with the `--skip-ingress` flag. -In this case, after completing the installation, manually configure the cluster's routing service, and create and register Git integrations. See the last step in [Install the hybrid runtime](#install-the-hybrid-runtime). - -**Ingress class** -Required. - -* CLI wizard: Select the ingress class for runtime installation from the list displayed. -* Silent install: Explicitly specify the ingress class through the `--ingress-class` flag. Otherwise, runtime installation fails. - -**Ingress host** -Required. -The IP address or host name of the ingress controller component. - -* CLI wizard: Automatically selects and displays the host, either from the cluster or the ingress controller associated with the **Ingress class**. -* Silent install: Add the `--ingress-host` flag. If a value is not provided, takes the host from the ingress controller associated with the **Ingress class**. - > Important: For AWS ALB, the ingress host is created post-installation. However, when prompted, add the domain name you will create in `Route 53` as the ingress host. - -**Insecure ingress hosts** -TLS certificates for the ingress host: -If the ingress host does not have a valid TLS certificate, you can continue with the installation in insecure mode, which disables certificate validation. - -* CLI wizard: Automatically detects and prompts you to confirm continuing the installation in insecure mode. -* Silent install: To continue with the installation in insecure mode, add the `--insecure-ingress-host` flag. - -**Internal ingress host** -Optional. -Enforce separation between internal (app-proxy) and external (webhook) communication by adding an internal ingress host for the app-proxy service in the internal network. -For both CLI wizard and Silent install: - -* For new runtime installations, add the `--internal-ingress-host` flag pointing to the ingress host for `app-proxy`. -* For existing installations, commit changes to the installation repository by modifying the `app-proxy ingress` and ` .yaml` - See [(Optional) Internal ingress host configuration for existing hybrid runtimes](#optional-internal-ingress-host-configuration-for-existing-hybrid-runtimes). - -{::nomarkdown} - -{:/} - - - -#### Git provider and repo flags -The Git provider defined for the runtime. - ->Because Codefresh creates a [shared configuration repo]({{site.baseurl}}/docs/reference/shared-configuration) for the runtimes in your account, the Git provider defined for the first runtime you install in your account is used for all the other runtimes in the same account. - -You can define any of the following Git providers: -* GitHub: - * [GitHub](#github) (the default Git provider) - * [GitHub Enterprise](#github-enterprise) -* GitLab: - * [GitLab Cloud](#gitlab-cloud) - * [GitLab Server](#gitlab-server) -* Bitbucket: - * [Bitbucket Cloud](#bitbucket-cloud) - * [Bitbucket Server](#bitbucket-server) - -{::nomarkdown} - -{:/} - - - -##### GitHub -GitHub is the default Git provider for hybrid runtimes. Being the default provider, for both the CLI wizard and Silent install, you need to provide only the repository URL and the Git runtime token. - -> For the required scopes, see [GitHub and GitHub Enterprise runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#github-and-github-enterprise-runtime-token-scopes). - -`--repo --git-token ` - -where: -* `--repo ` (required), is the `HTTPS` clone URL of the Git repository for the runtime installation, including the `.git` suffix. Copy the clone URL from your GitHub website (see [Cloning with HTTPS URLs](https://docs.github.com/en/get-started/getting-started-with-git/about-remote-repositories#cloning-with-https-urls){:target="\_blank"}). - If the repo doesn't exist, copy an existing clone URL and change the name of the repo. Codefresh creates the repository during runtime installation. - - Repo URL format: - `https://github.com/ /reponame>.git[/subdirectory][?ref=branch]` - where: - * ` / ` is your username or organization name, followed by the name of the repo, identical to the HTTPS clone URL. For example, `https://github.com/nr-codefresh/codefresh.io.git`. - * `[/subdirectory]` (optional) is the path to a subdirectory within the repo. When omitted, the runtime is installed in the root of the repository. For example, `/runtimes/defs`. - * `[?ref=branch]` (optional) is the `ref` queryParam to select a specific branch. When omitted, the runtime is installed in the default branch. For example, `codefresh-prod`. - - Example: - `https://github.com/nr-codefresh/codefresh.io.git/runtimes/defs?ref=codefresh-prod` -* `--git-token ` (required), is the Git token authenticating access to the runtime installation repository (see [GitHub runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#github-and-github-enterprise-runtime-token-scopes)). - -{::nomarkdown} - -{:/} - -##### GitHub Enterprise - -> For the required scopes, see [GitHub and GitHub Enterprise runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#github-and-github-enterprise-runtime-token-scopes). - - -`--enable-git-providers --provider github --repo --git-token ` - -where: -* `--enable-git-providers` (required), indicates that you are not using the default Git provider for the runtime. -* `--provider github` (required), defines GitHub Enterprise as the Git provider for the runtime and the account. -* `--repo ` (required), is the `HTTPS` clone URL of the Git repository for the runtime installation, including the `.git` suffix. Copy the clone URL for HTTPS from your GitHub Enterprise website (see [Cloning with HTTPS URLs](https://docs.github.com/en/get-started/getting-started-with-git/about-remote-repositories#cloning-with-https-urls){:target="\_blank"}). - If the repo doesn't exist, copy an existing clone URL and change the name of the repo. Codefresh creates the repository during runtime installation. - Repo URL format: - - `https://ghe-trial.devops.cf-cd.com/ / .git[/subdirectory][?ref=branch]` - where: - * ` / ` is your username or organization name, followed by the name of the repo. For example, `codefresh-io/codefresh.io.git`. - * `[/subdirectory]` (optional) is the path to a subdirectory within the repo. When omitted, the runtime is installed in the root of the repository. For example, `/runtimes/defs`. - * `[?ref=branch]` (optional) is the `ref` queryParam to select a specific branch. When omitted, the runtime is installed in the default branch. For example, `codefresh-prod`. - - Example: - `https://ghe-trial.devops.cf-cd.com/codefresh-io/codefresh.io.git/runtimes/defs?ref=codefresh-prod` -* `--git-token ` (required), is the Git token authenticating access to the runtime installation repository (see [GitHub runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#github-and-github-enterprise-runtime-token-scopes)). - - -{::nomarkdown} - -{:/} - -##### GitLab Cloud -> For the required scopes, see [GitLab Cloud and GitLab Server runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#gitlab-cloud-and-gitlab-server-runtime-token-scopes). - - -`--enable-git-providers --provider gitlab --repo --git-token ` - -where: -* `--enable-git-providers`(required), indicates that you are not using the default Git provider for the runtime. -* `--provider gitlab` (required), defines GitLab Cloud as the Git provider for the runtime and the account. -* `--repo ` (required), is the `HTTPS` clone URL of the Git project for the runtime installation, including the `.git` suffix. Copy the clone URL for HTTPS from your GitLab website. - If the repo doesn't exist, copy an existing clone URL and change the name of the repo. Codefresh creates the repository during runtime installation. - - > Important: You must create the group with access to the project prior to the installation. - - Repo URL format: - - `https://gitlab.com/ / .git[/subdirectory][?ref=branch]` - where: - * ` ` is either your username, or if your project is within a group, the front-slash separated path to the project. For example, `nr-codefresh` (owner), or `parent-group/child-group` (group hierarchy) - * ` ` is the name of the project. For example, `codefresh`. - * `[/subdirectory]` (optional) is the path to a subdirectory within the repo. When omitted, the runtime is installed in the root of the repository. For example, `/runtimes/defs`. - * `[?ref=branch]` (optional) is the `ref` queryParam to select a specific branch. When omitted, the runtime is installed in the default branch. For example, `codefresh-prod`. - - Examples: - `https://gitlab.com/nr-codefresh/codefresh.git/runtimes/defs?ref=codefresh-prod` (owner) - - `https://gitlab.com/parent-group/child-group/codefresh.git/runtimes/defs?ref=codefresh-prod` (group hierarchy) - -* `--git-token ` (required), is the Git token authenticating access to the runtime installation repository (see [GitLab runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#gitlab-cloud-and-gitlab-server-runtime-token-scopes)). - - -{::nomarkdown} - -{:/} - - - -##### GitLab Server - -> For the required scopes, see [GitLab Cloud and GitLab Server runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#gitlab-cloud-and-gitlab-server-runtime-token-scopes). - -`--enable-git-providers --provider gitlab --repo --git-token ` - -where: -* `--enable-git-providers` (required), indicates that you are not using the default Git provider for the runtime. -* `--provider gitlab` (required), defines GitLab Server as the Git provider for the runtime and the account. -* `--repo ` (required), is the `HTTPS` clone URL of the Git repository for the runtime installation, including the `.git` suffix. - If the project doesn't exist, copy an existing clone URL and change the name of the project. Codefresh creates the project during runtime installation. - - > Important: You must create the group with access to the project prior to the installation. - - Repo URL format: - `https://gitlab-onprem.devops.cf-cd.com/ / .git[/subdirectory][?ref=branch]` - where: - * ` ` is your username, or if the project is within a group or groups, the name of the group. For example, `nr-codefresh` (owner), or `parent-group/child-group` (group hierarchy) - * ` ` is the name of the project. For example, `codefresh`. - * `[/subdirectory]` (optional) is the path to a subdirectory within the repo. When omitted, the runtime is installed in the root of the repository. For example, `/runtimes/defs`. - * `[?ref=branch]` (optional) is the `ref` queryParam to select a specific branch. When omitted, the runtime is installed in the default branch. For example, `codefresh-prod`. - - Examples: - `https://gitlab-onprem.devops.cf-cd.com/nr-codefresh/codefresh.git/runtimes/defs?ref=codefresh-prod` (owner) - - `https://gitlab-onprem.devops.cf-cd.com/parent-group/child-group/codefresh.git/runtimes/defs?ref=codefresh-prod` (group hierarchy) - -* `--git-token ` (required), is the Git token authenticating access to the runtime installation repository (see [GitLab runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#gitlab-cloud-and-gitlab-server-runtime-token-scopes)). - - -{::nomarkdown} - -{:/} - -##### Bitbucket Cloud -> For the required scopes, see [Bitbucket runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#bitbucket-cloud-and-bitbucket-server-runtime-token-scopes). - - -`--enable-git-providers --provider bitbucket --repo --git-user --git-token ` - -where: -* `--enable-git-providers` (required), indicates that you are not using the default Git provider for the runtime. -* `--provider gitlab` (required), defines Bitbucket Cloud as the Git provider for the runtime and the account. -* `--repo ` (required), is the `HTTPS` clone URL of the Git repository for the runtime installation, including the `.git` suffix. - If the project doesn't exist, copy an existing clone URL and change the name of the project. Codefresh creates the project during runtime installation. - >Important: Remove the username, including @ from the copied URL. - - Repo URL format: - - `https://bitbucket.org .git[/subdirectory][?ref=branch]` - where: - * ` ` is your workspace ID. For example, `nr-codefresh`. - * ` ` is the name of the repository. For example, `codefresh`. - * `[/subdirectory]` (optional) is the path to a subdirectory within the repo. When omitted, the runtime is installed in the root of the repository. For example, `/runtimes/defs`. - * `[?ref=branch]` (optional) is the `ref` queryParam to select a specific branch. When omitted, the runtime is installed in the default branch. For example, `codefresh-prod`. - - Example: - `https://bitbucket.org/nr-codefresh/codefresh.git/runtimes/defs?ref=codefresh-prod` -* `--git-user ` (required), is your username for the Bitbucket Cloud account. -* `--git-token ` (required), is the Git token authenticating access to the runtime installation repository (see [Bitbucket runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#bitbucket-cloud-and-bitbucket-server-runtime-token-scopes)). - - -{::nomarkdown} - -{:/} - -##### Bitbucket Server - -> For the required scopes, see [Bitbucket runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#bitbucket-cloud-and-bitbucket-server-runtime-token-scopes). - - -`--enable-git-providers --provider bitbucket-server --repo --git-user --git-token ` - -where: -* `--enable-git-providers` (required), indicates that you are not using the default Git provider for the runtime. -* `--provider gitlab` (required), defines Bitbucket Cloud as the Git provider for the runtime and the account. -* `--repo ` (required), is the `HTTPS` clone URL of the Git repository for the runtime installation, including the `.git` suffix. - If the project doesn't exist, copy an existing clone URL and change the name of the project. Codefresh then creates the project during runtime installation. - >Important: Remove the username, including @ from the copied URL. - - Repo URL format: - - `https://bitbucket-server-8.2.devops.cf-cd.com:7990/scm/ / .git[/subdirectory][?ref=branch]` - where: - * ` ` is your username or organization name. For example, `codefresh-io.`. - * ` ` is the name of the repo. For example, `codefresh`. - * `[/subdirectory]` (optional) is the path to a subdirectory within the repo. When omitted, the runtime is installed in the root of the repository. For example, `/runtimes/defs`. - * `[?ref=branch]` (optional) is the `ref` queryParam to select a specific branch. When omitted, the runtime is installed in the default branch. For example, `codefresh-prod`. - - Example: - `https://bitbucket-server-8.2.devops.cf-cd.com:7990/scm/codefresh-io/codefresh.git/runtimes/defs?ref=codefresh-prod` -* `--git-user ` (required), is your username for the Bitbucket Server account. -* `--git-token ` (required), is the Git token authenticating access to the runtime installation repository (see [Bitbucket runtime token scopes]({{site.baseurl}}/docs/reference/git-tokens/#bitbucket-cloud-and-bitbucket-server-runtime-token-scopes)). - -{::nomarkdown} - -{:/} - -#### Codefresh resource flags -**Codefresh demo resources** -Optional. -Install demo pipelines to use as a starting point to create your own pipelines. We recommend installing the demo resources as these are used in our quick start tutorials. - -* Silent install: Add the `--demo-resources` flag, and define its value as `true` (default), or `false`. For example, `--demo-resources=true` - -**Insecure flag** -For _on-premises installations_, if the Ingress controller does not have a valid SSL certificate, to continue with the installation, add the `--insecure` flag to the installation command. - -{::nomarkdown} - -{:/} - - -### Install the Codefresh CLI - -Install the Codefresh CLI using the option that best suits you: `curl`, `brew`, or standard download. -If you are not sure which OS to select for `curl`, simply select one, and Codefresh automatically identifies and selects the right OS for CLI installation. - -{::nomarkdown} - -{:/} - -### Install the hybrid runtime - -**Before you begin** -* Make sure you meet the [minimum requirements]({{site.baseurl}}/docs/runtime/requirements/#minimum-requirements) for runtime installation -* Make sure you have [runtime token with the required scopes from your Git provdier]({{site.baseurl}}/docs/reference/git-tokens) -* [Download or upgrade to the latest version of the CLI]({{site.baseurl}}/docs/clients/csdp-cli/#upgrade-codefresh-cli) -* Review [Hybrid runtime installation flags](#hybrid-runtime-installation-flags) -* Make sure your ingress controller is configured correctly: - * [Ambasador ingress configuration]({{site.baseurl}}/docs/runtime/requirements/#ambassador-ingress-configuration) - * [AWS ALB ingress configuration]({{site.baseurl}}/docs/runtime/requirements/#alb-aws-ingress-configuration) - * [Istio ingress configuration]({{site.baseurl}}/docs/runtime/requirements/#istio-ingress-configuration) - * [NGINX Enterprise ingress configuration]({{site.baseurl}}/docs/runtime/requirements/#nginx-enterprise-ingress-configuration) - * [NGINX Community ingress configuration]({{site.baseurl}}/docs/runtime/requirements/#nginx-community-version-ingress-configuration) - * [Traefik ingress configuration]({{site.baseurl}}/docs/runtime/requirements/#traefik-ingress-configuration) - - -{::nomarkdown} - -{:/} - -**How to** - -1. Do one of the following: - * If this is your first hybrid runtime installation, in the Welcome page, select **+ Install Runtime**. - * If you have provisioned a hybrid runtime, to provision additional runtimes, in the Codefresh UI, go to [**Runtimes**](https://g.codefresh.io/2.0/account-settings/runtimes){:target="\_blank"}. -1. Click **+ Add Runtimes**, and then select **Hybrid Runtimes**. -1. Do one of the following: - * CLI wizard: Run `cf runtime install`, and follow the prompts to enter the required values. - * Silent install: Pass the required flags in the install command: - `cf runtime install --repo --git-token --silent` - For the list of flags, see [Hybrid runtime installation flags](#hybrid-runtime-installation-flags). -1. If relevant, complete the configuration for these ingress controllers: - * [ALB AWS: Alias DNS record in route53 to load balancer]({{site.baseurl}}/docs/runtime/requirements/#alias-dns-record-in-route53-to-load-balancer) - * [Istio: Configure cluster routing service]({{site.baseurl}}/docs/runtime/requirements/#cluster-routing-service) - * [NGINX Enterprise ingress controller: Patch certificate secret]({{site.baseurl}}/docs/runtime/requirements/#patch-certificate-secret) -1. If you bypassed installing ingress resources with the `--skip-ingress` flag for ingress controllers not in the supported list, create and register Git integrations using these commands: - `cf integration git add default --runtime --api-url ` - `cf integration git register default --runtime --token ` - - -{::nomarkdown} - -{:/} - -### Hybrid runtime components - -**Git repositories** -* Runtime install repository: The installation repo contains three folders: apps, bootstrap and projects, to manage the runtime itself with Argo CD. -* Git source repository: Created with the name `[repo_name]_git-source`. This repo stores manifests for pipelines with sources, events, workflow templates. See [Add Git Sources to runtimes]({{site.baseurl}}/docs/runtime/git-sources/). - -* Shared configuration repository: Stores configuration and resource manifests that can be shared across runtimes, such as integration resources. See [Shared configuration repository]({{site.baseurl}}/docs/reference/shared-configuration/) - -**Argo CD components** -* Project, comprising an Argo CD AppProject and an ApplicationSet -* Installations of the following applications in the project: - * Argo CD - * Argo Workflows - * Argo Events - * Argo Rollouts - -**Codefresh-specific components** -* Codefresh Applications in the Argo CD AppProject: - * App-proxy facilitating behind-firewall access to Git - * Git Source entity that references the`[repo_name]_git-source` - -Once the hybrid runtime is successfully installed, it is provisioned on the Kubernetes cluster, and displayed in the **Runtimes** page. - -{::nomarkdown} - -{:/} - - -### (Optional) Internal ingress host configuration for existing hybrid runtimes -If you already have provisioned hybrid runtimes, to use an internal ingress host for app-proxy communication and an external ingress host to handle webhooks, change the specs for the `Ingress` and `Runtime` resources in the runtime installation repository. Use the examples as guidelines. - -` /apps/app-proxy/overlays/ /ingress.yaml`: change `host` - -```yaml -apiVersion: networking.k8s.io/v1 -kind: Ingress -metadata: - name: codefresh-cap-app-proxy - namespace: codefresh #replace with your runtime name -spec: - ingressClassName: nginx - rules: - - host: my-internal-ingress-host # replace with the internal ingress host for app-proxy - http: - paths: - - backend: - service: - name: cap-app-proxy - port: - number: 3017 - path: /app-proxy/ - pathType: Prefix -``` - -`../ /bootstrap/ .yaml`: add `internalIngressHost` - -```yaml -apiVersion: v1 -data: - base-url: https://g.codefresh.io - runtime: | - apiVersion: codefresh.io/v1alpha1 - kind: Runtime - metadata: - creationTimestamp: null - name: codefresh #replace with your runtime name - namespace: codefresh #replace with your runtime name - spec: - bootstrapSpecifier: github.com/codefresh-io/cli-v2/manifests/argo-cd - cluster: https://7DD8390300DCEFDAF87DC5C587EC388C.gr7.us-east-1.eks.amazonaws.com - components: - - isInternal: false - name: events - type: kustomize - url: github.com/codefresh-io/cli-v2/manifests/argo-events - wait: true - - isInternal: false - name: rollouts - type: kustomize - url: github.com/codefresh-io/cli-v2/manifests/argo-rollouts - wait: false - - isInternal: false - name: workflows - type: kustomize - url: github.com/codefresh-io/cli-v2/manifests/argo-workflows - wait: false - - isInternal: false - name: app-proxy - type: kustomize - url: github.com/codefresh-io/cli-v2/manifests/app-proxy - wait: false - defVersion: 1.0.1 - ingressClassName: nginx - ingressController: k8s.io/ingress-nginx - ingressHost: https://support.cf.com/ - internalIngressHost: https://my-internal-ingress-host # add this line and replace my-internal-ingress-host with your internal ingress host - repo: https://github.com/NimRegev/my-codefresh.git - version: 99.99.99 -``` - - -### Related articles -[Add external clusters to runtimes]({{site.baseurl}}/docs/runtime/managed-cluster/) -[Manage provisioned runtimes]({{site.baseurl}}/docs/runtime/monitor-manage-runtimes/) -[Monitor provisioned hybrid runtimes]({{site.baseurl}}/docs/runtime/monitoring-troubleshooting/) -[Troubleshoot hybrid runtime installation]({{site.baseurl}}/docs/troubleshooting/runtime-issues/) diff --git a/_docs/runtime/installation_original.md b/_docs/runtime/installation_original.md deleted file mode 100644 index a9624bc7..00000000 --- a/_docs/runtime/installation_original.md +++ /dev/null @@ -1,338 +0,0 @@ ---- -title: "Install hybrid runtimes" -description: "" -group: runtime -toc: true ---- - -If you have a hybrid environment, you can provision one or more hybrid runtimes in your Codefresh account. The hybrid runtime comprises Argo CD components and Codefresh-specific components. The Argo CD components are derived from a fork of the Argo ecosystem, and do not correspond to the open-source versions available. - -> If you have Hosted GitOps, to provision a hosted runtime, see [Provision a hosted runtime]({{site.baseurl}}/docs/runtime/hosted-runtime/#1-provision-hosted-runtime) in [Set up a hosted (Hosted GitOps) environment]({{site.baseurl}}/docs/runtime/hosted-runtime/). - -There are two parts to installing a hybrid runtime: - -1. Installing the Codefresh CLI -2. Installing the hybrid runtime from the CLI, either through the CLI wizard or via silent installation. - The hybrid runtime is installed in a specific namespace on your cluster. You can install more runtimes on different clusters in your deployment. - Every hybrid runtime installation makes commits to two Git repos: - - * Runtime install repo: The installation repo that manages the hybrid runtime itself with Argo CD. If the repo URL does not exist, runtime creates it automatically. - * Git Source repo: Created automatically during runtime installation. The repo where you store manifests to run CodefreshCodefresh pipelines. - -See also [Codefresh architecture]({{site.baseurl}}/docs/getting-started/architecture). - -### Installing the Codefresh CLI - -Install the Codefresh CLI using the option that best suits you: `curl`, `brew`, or standard download. -If you are not sure which OS to select for `curl`, simply select one, and Codefresh automatically identifies and selects the right OS for CLI installation. - -### Installing the hybrid runtime - -1. Do one of the following: - * If this is your first hybrid runtime installation, in the Welcome page, select **+ Install Runtime**. - * If you have provisioned a hybrid runtime, to provision additional runtimes, in the Codefresh UI, go to [**Runtimes**](https://g.codefresh.io/2.0/account-settings/runtimes){:target="\_blank"}, and select **+ Add Runtimes**. -1. Run: - * CLI wizard: Run `cf runtime install`, and follow the prompts to enter the required values. - * Silent install: Pass the required flags in the install command: - `cf runtime install --repo --git-token --silent` - For the list of flags, see _Hybrid runtime flags_. - -> Note: -> Hybrid runtime installation starts by checking network connectivity and the K8s cluster server version. - To skip these tests, pass the `--skip-cluster-checks` flag. - -#### Hybrid runtime flags - -**Runtime name** -Required. -The runtime name must start with a lower-case character, and can include up to 62 lower-case characters and numbers. -* CLI wizard: Add when prompted. -* Silent install: Required. - -**Namespace resource labels** -Optional. -The label of the namespace resource to which you are installing the hybrid runtime. You can add more than one label. Labels are required to identity the networks that need access during installation, as is the case when using services meshes such as Istio for example. - -* CLI wizard and Silent install: Add the `--namespace-labels` flag, and define the labels in `key=value` format. Separate multiple labels with `commas`. - -**Kube context** -Required. -The cluster defined as the default for `kubectl`. If you have more than one Kube context, the current context is selected by default. - -* CLI wizard: Select the Kube context from the list displayed. -* Silent install: Explicitly specify the Kube context with the `--context` flag. - -**Ingress class** -Required. -If you have more than one ingress class configured on your cluster: - -* CLI wizard: Select the ingress class for runtime installation from the list displayed. -* Silent install: Explicitly specify the ingress class through the `--ingress-class` flag. Otherwise, runtime installation fails. - -**Ingress host** -Required. -The IP address or host name of the ingress controller component. - -* CLI wizard: Automatically selects and displays the host, either from the cluster or the ingress controller associated with the **Ingress class**. -* Silent install: Add the `--ingress-host` flag. If a value is not provided, takes the host from the ingress controller associated with the **Ingress class**. - > Important: For AWS ALB, the ingress host is created post-installation. However, when prompted, add the domain name you will create in `Route 53` as the ingress host. - -SSL certificates for the ingress host: -If the ingress host does not have a valid SSL certificate, you can continue with the installation in insecure mode, which disables certificate validation. - -* CLI wizard: Automatically detects and prompts you to confirm continuing with the installation in insecure mode. -* Silent install: To continue with the installation in insecure mode, add the `--insecure-ingress-host` flag. - -**Internal ingress host** -Optional. -Enforce separation between internal (app-proxy) and external (webhook) communication by adding an internal ingress host for the app-proxy service in the internal network. -For both CLI wizard and Silent install: - -* For new runtime installations, add the `--internal-ingress-host` flag pointing to the ingress host for `app-proxy`. -* For existing installations, commit changes to the installation repository by modifying the `app-proxy ingress` and ` .yaml` - See _Internal ingress host configuration (optional for existing runtimes only)_ in [Post-installation configuration](#post-installation-configuration). - -**Ingress resources** -Optional. -If you have a different routing service (not NGINX), bypass installing ingress resources with the `--skip-ingress` flag. -In this case, after completing the installation, manually configure the cluster's routing service, and create and register Git integrations. See _Cluster routing service_ in [Post-installation configuration](#post-installation-configuration). - -**Shared configuration repository** -The Git repository per runtime account with shared configuration manifests. -* CLI wizard and Silent install: Add the `--shared-config-repo` flag and define the path to the shared repo. - -**Insecure flag** -For _on-premises installations_, if the Ingress controller does not have a valid SSL certificate, to continue with the installation, add the `--insecure` flag to the installation command. - -**Repository URLs** -The GitHub repository to house the installation definitions. - -* CLI wizard: If the repo doesn't exist, Codefresh creates it during runtime installation. -* Silent install: Required. Add the `--repo` flag. - -**Git runtime token** -Required. -The Git token authenticating access to the GitHub installation repository. -* Silent install: Add the `--git-token` flag. - -**Codefresh demo resources** -Optional. -Install demo pipelines to use as a starting point to create your own pipelines. We recommend installing the demo resources as these are used in our quick start tutorials. - -* Silent install: Add the `--demo-resources` flag. By default, set to `true`. - -### Hybrid runtime components - -**Git repositories** - -* Runtime install repo: The installation repo contains three folders: apps, bootstrap and projects, to manage the runtime itself with Argo CD. -* Git source repository: Created with the name `[repo_name]_git-source`. This repo stores manifests for pipelines with sources, events, workflow templates. - -**Argo CD components** - -* Project, comprising an Argo CD AppProject and an ApplicationSet -* Installations of the following applications in the project: - * Argo CD - * Argo Workflows - * Argo Events - * Argo Rollouts - -**Codefresh-specific components** - -* Codefresh Applications in the Argo CD AppProject: - * App-proxy facilitating behind-firewall access to Git - * Git Source entity that references the`[repo_name]_git-source` - -Once the hybrid runtime is successfully installed, it is provisioned on the Kubernetes cluster, and displayed in the **Runtimes** page. - -### Hybrid runtime post-installation configuration - -After provisioning a hybrid runtime, configure additional settings for the following: - -* NGINX Enterprise installations (with and without NGINX Ingress Operator) -* AWS ALB installations -* Cluster routing service if you bypassed installing ingress resources -* (Existing hybrid runtimes) Internal and external ingress host specifications -* Register Git integrations - - - -#### AWS ALB post-install configuration - -For AWS ALB installations, do the following: - -* Create an `Alias` record in Amazon Route 53 -* Manually register Git integrations - see _Git integration registration_. - -Create an `Alias` record in Amazon Route 53, and map your zone apex (example.com) DNS name to your Amazon CloudFront distribution. -For more information, see [Creating records by using the Amazon Route 53 console](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-creating.html){:target="\_blank"}. - -{% include image.html - lightbox="true" - file="/images/runtime/post-install-alb-ingress.png" - url="/images/runtime/post-install-alb-ingress.png" - alt="Route 53 record settings for AWS ALB" - caption="Route 53 record settings for AWS ALB" - max-width="30%" -%} - -#### Configure cluster routing service - -If you bypassed installing ingress resources with the `--skip-ingress` flag, configure the `host` for the Ingress, or the VirtualService for Istio if used, to route traffic to the `app-proxy` and `webhook` services, as in the examples below. - -**Ingress resource example for `app-proxy`:** - -```yaml -apiVersion: networking.k8s.io/v1 -kind: Ingress -metadata: - name: codefresh-cap-app-proxy - namespace: codefresh -spec: - ingressClassName: alb - rules: - - host: my.support.cf-cd.com # replace with your host name - http: - paths: - - backend: - service: - name: cap-app-proxy - port: - number: 3017 - path: /app-proxy/ - pathType: Prefix -``` - -**`VirtualService` examples for `app-proxy` and `webhook`:** - -```yaml -apiVersion: networking.istio.io/v1alpha3 -kind: VirtualService -metadata: - namespace: test-runtime3 # replace with your runtime name - name: cap-app-proxy -spec: - hosts: - - my.support.cf-cd.com # replace with your host name - gateways: - - my-gateway - http: - - match: - - uri: - prefix: /app-proxy - route: - - destination: - host: cap-app-proxy - port: - number: 3017 -``` - -```yaml -apiVersion: networking.istio.io/v1alpha3 -kind: VirtualService -metadata: - namespace: test-runtime3 # replace with your runtime name - name: csdp-default-git-source -spec: - hosts: - - my.support.cf-cd.com # replace with your host name - gateways: - - my-gateway - http: - - match: - - uri: - prefix: /webhooks/test-runtime3/push-github # replace `test-runtime3` with your runtime name - route: - - destination: - host: push-github-eventsource-svc - port: - number: 80 -``` -Continue with [Git integration registration](#git-integration-registration) in this article. - -#### Internal ingress host configuration (optional for existing hybrid runtimes only) - -If you already have provisioned hybrid runtimes, to use an internal ingress host for app-proxy communication and an external ingress host to handle webhooks, change the specs for the `Ingress` and `Runtime` resources in the runtime installation repository. Use the examples as guidelines. - -` /apps/app-proxy/overlays/ /ingress.yaml`: change `host` - -```yaml -apiVersion: networking.k8s.io/v1 -kind: Ingress -metadata: - name: codefresh-cap-app-proxy - namespace: codefresh #replace with your runtime name -spec: - ingressClassName: nginx - rules: - - host: my-internal-ingress-host # replace with the internal ingress host for app-proxy - http: - paths: - - backend: - service: - name: cap-app-proxy - port: - number: 3017 - path: /app-proxy/ - pathType: Prefix -``` - -`../ /bootstrap/ .yaml`: add `internalIngressHost` - -```yaml -apiVersion: v1 -data: - base-url: https://g.codefresh.io - runtime: | - apiVersion: codefresh.io/v1alpha1 - kind: Runtime - metadata: - creationTimestamp: null - name: codefresh #replace with your runtime name - namespace: codefresh #replace with your runtime name - spec: - bootstrapSpecifier: github.com/codefresh-io/cli-v2/manifests/argo-cd - cluster: https://7DD8390300DCEFDAF87DC5C587EC388C.gr7.us-east-1.eks.amazonaws.com - components: - - isInternal: false - name: events - type: kustomize - url: github.com/codefresh-io/cli-v2/manifests/argo-events - wait: true - - isInternal: false - name: rollouts - type: kustomize - url: github.com/codefresh-io/cli-v2/manifests/argo-rollouts - wait: false - - isInternal: false - name: workflows - type: kustomize - url: github.com/codefresh-io/cli-v2/manifests/argo-workflows - wait: false - - isInternal: false - name: app-proxy - type: kustomize - url: github.com/codefresh-io/cli-v2/manifests/app-proxy - wait: false - defVersion: 1.0.1 - ingressClassName: nginx - ingressController: k8s.io/ingress-nginx - ingressHost: https://support.cf.com/ - internalIngressHost: https://my-internal-ingress-host # add this line and replace my-internal-ingress-host with your internal ingress host - repo: https://github.com/NimRegev/my-codefresh.git - version: 99.99.99 -``` - -#### Git integration registration - -If you bypassed installing ingress resources with the `--skip-ingress` flag, or if AWS ALB is your ingress controller, create and register Git integrations using these commands: - `cf integration git add default --runtime --api-url ` - - `cf integration git register default --runtime --token ` - -### Related articles -[Add external clusters to runtimes]({{site.baseurl}}/docs/runtime/managed-cluster/) -[Add Git Sources to runtimes]({{site.baseurl}}/docs/runtime/git-sources/) -[Manage provisioned runtimes]({{site.baseurl}}/docs/runtime/monitor-manage-runtimes/) -[Monitor provisioned hybrid runtimes]({{site.baseurl}}/docs/runtime/monitoring-troubleshooting/) -[Troubleshoot runtime installation]({{site.baseurl}}/docs/troubleshooting/runtime-issues/) diff --git a/_docs/runtime/monitor-manage-runtimes.md b/_docs/runtime/monitor-manage-runtimes.md deleted file mode 100644 index 189b2b08..00000000 --- a/_docs/runtime/monitor-manage-runtimes.md +++ /dev/null @@ -1,332 +0,0 @@ ---- -title: "Manage provisioned runtimes" -description: "" -group: runtime -redirect_from: - - /monitor-manage-runtimes/ - - /monitor-manage-runtimes -toc: true ---- - - -The **Runtimes** page displays the provisioned runtimes in your account, both hybrid, and the hosted runtime if you have one. - -View runtime components and information in List or Topology view formats, and upgrade, uninstall, and migrate runtimes. - -{% include - image.html - lightbox="true" - file="/images/runtime/runtime-list-view.png" - url="/images/runtime/runtime-list-view.png" - alt="Runtime List View" - caption="Runtime List View" - max-width="70%" -%} - -Select the view mode to view runtime components and information, and manage provisioned runtimes in the view mode that suits you. - - -Manage provisioned runtimes: -* [Add managed clusters to hybrid or hosted runtimes]({{site.baseurl}}/docs/runtime/managed-cluster/)) -* [Add and manage Git Sources associated with hybrid or hosted runtimes]({{site.baseurl}}/docs/runtime/git-sources/)) -* [Upgrade provisioned hybrid runtimes](#hybrid-upgrade-provisioned-runtimes) -* [Uninstall provisioned runtimes](#uninstall-provisioned-runtimes) -* [Migrate ingress-less hybrid runtimes]((#hybrid-migrate-ingress-less-runtimes)) - -> Unless specified otherwise, management options are common to both hybrid and hosted runtimes. If an option is valid only for hybrid runtimes, it is indicated as such. - -* Add managed clusters to hybrid or hosted runtimes (see [Adding & managing external clusters]({{site.baseurl}}/docs/runtime/managed-cluster/)) -* Add and manage Git Sources associated with hybrid or hosted runtimes (see [Adding & managing Git Sources]({{site.baseurl}}/docs/runtime/git-sources/)) -* Upgrade provisioned hybrid runtimes -* Uninstall hybrid or hosted runtimes -* Update Git runtime tokens - -To monitor provisioned hybrid runtimes, including recovering runtimes for failed clusters, see [Monitor provisioned hybrid runtimes]({{site.baseurl}}/docs/runtime/monitoring-troubleshooting/). - -### Runtime views - -View provisioned hybrid and hosted runtimes in List or Topology view formats. - -* List view: The default view, displays the list of provisioned runtimes, the clusters managed by them, and Git Sources. -* Topology view: Displays a hierarchical view of runtimes and the clusters managed by them, with health and sync status of each cluster. - -#### List view - -The List view is a grid-view of the provisioned runtimes. - -Here is an example of the List view for runtimes. -{% include - image.html - lightbox="true" - file="/images/runtime/runtime-list-view.png" - url="/images/runtime/runtime-list-view.png" - alt="Runtime List View" - caption="Runtime List View" - max-width="70%" -%} - -Here is a description of the information in the List View. - -{: .table .table-bordered .table-hover} -| List View Item| Description | -| -------------- | ---------------- | -|**Name**| The name of the provisioned Codefresh runtime. | -|**Type**| The type of runtime provisioned, and can be **Hybrid** or **Hosted**. | -|**Cluster/Namespace**| The K8s API server endpoint, as well as the namespace with the cluster. | -|**Modules**| The modules installed based on the type of provisioned runtime. Hybrid runtimes include CI amnd CD Ops modules. Hosted runtimes inlcude CD Ops. | -|**Managed Cluster**| The number of managed clusters if any, for the runtime. To view list of managed clusters, select the runtime, and then the **Managed Clusters** tab. To work with managed clusters, see [Adding external clusters to runtimes]({{site.baseurl}}/docs/runtime/managed-cluster).| -|**Version**| The version of the runtime currently installed. **Update Available!** indicates there are later versions of the runtime. To see all the commits to the runtime, mouse over **Update Available!**, and select **View Complete Change Log**. -|**Last Updated**| The most recent update information from the runtime to the Codefresh platform. Updates are sent to the platform typically every few minutes. Longer update intervals may indicate networking issues.| -|**Sync Status**| The health and sync status of the runtime or cluster. {::nomarkdown} - indicates health or sync errors in the runtime, or a managed cluster if one was added to the runtime. The runtime name is colored red.
- indicates that the runtime is being synced to the cluster on which it is provisioned.
- indicates the local cluster, always displayed as `in-cluster`. The in-cluster server URL is always set to `https://kubernetes.default.svc/`.
- indicates a managed cluster.
- select to add a new managed cluster.
- indicates health or sync errors in the runtime, or a managed cluster if one was added to the runtime. The runtime or cluster node is bordered in red and the name is colored red.
- indicates that the runtime is being synced to the cluster on which it is provisioned.
- Find a runtime or its clusters by typing part of the runtime/cluster name, and then navigate to the entries found.
- Topology view options: Resize to window, zoom in, zoom out, full screen view.
--git-token --silent` - where: - ` ` is a valid runtime token with the `repo` and `admin-repo.hook` scopes. - -**CLI wizard-based upgrade** - -1. In the Codefresh UI, make sure you are in [Runtimes](https://g.codefresh.io/2.0/account-settings/runtimes){:target="\_blank"}. -1. Switch to either the **List View** or to the **Topology View**. -1. **List view**: - * Select the runtime name. - * To see all the commits to the runtime, in the Version column, mouse over **Update Available!**, and select **View Complete Change Log**. - * On the top-right, select **Upgrade**. - - {% include - image.html - lightbox="true" - file="/images/runtime/runtime-list-view-upgrade.png" - url="/images/runtime/runtime-list-view-upgrade.png" - alt="List View: Upgrade runtime option" - caption="List View: Upgrade runtime option" - max-width="30%" - %} - - **Topology view**: - Select the runtime cluster, and from the panel, select the three dots and then select **Upgrade Runtime**. - {% include - image.html - lightbox="true" - file="/images/runtime/runtiime-topology-upgrade.png" - url="/images/runtime/runtiime-topology-upgrade.png" - alt="Topology View: Upgrade runtime option" - caption="Topology View: Upgrade runtime option" - max-width="30%" -%} - -{:start="4"} - -1. If you have already installed the Codefresh CLI, in the Install Upgrades panel, copy the upgrade command. - - {% include - image.html - lightbox="true" - file="/images/runtime/install-upgrades.png" - url="/images/runtime/install-upgrades.png" - alt="Upgrade runtime" - caption="Upgrade runtime panel" - max-width="30%" -%} - -{:start="5"} -1. In your terminal, paste the command, and do the following: - * Update the Git token value. - * To manually define the shared configuration repo, add the `--shared-config-repo` flag with the path to the repo. -1. Confirm to start the upgrade. - - - - -### Uninstall provisioned runtimes - -Uninstall provisioned hybrid and hosted runtimes that are not in use. Uninstall a runtime by running a silent uninstall, or through the CLI wizard. -> Uninstalling a runtime removes the Git Sources and managed clusters associated with the runtime. - -**Before you begin** -For both types of uninstalls, make sure you have: - -* The latest version of the Codefresh CLI -* A valid runtime Git token -* The Kube context from which to uninstall the provisioned runtime - -**Silent uninstall** -Pass the mandatory flags in the uninstall command: - `cf runtime uninstall --git-token
- "
+```
+`CONTENT_SECURITY_POLICY` is the string describing content policies. Use semi-colons to separate between policies.
+`CONTENT_SECURITY_POLICY_REPORT_TO` is a comma-separated list of JSON objects. Each object must have a name and an array of endpoints that receive the incoming CSP reports.
+
+For detailed information, see the [Content Security Policy article on MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP).
+
+### Enable x-hub-signature-256 signature for GitHub AE
+Add the `USE_SHA256_GITHUB_SIGNATURE` environment variable to **cfapi** deployment in `config.yaml`.
+```yaml
+cfapi:
+ env:
+ USE_SHA256_GITHUB_SIGNATURE: "true"
+```
+
+For detailed information, see the [Securing your webhooks](https://docs.github.com/en/developers/webhooks-and-events/webhooks/securing-your-webhooks) and [Webhooks](https://docs.github.com/en/github-ae@latest/rest/webhooks).
+
+
+## Using existing external services for data storage/messaging
+
+Normally the Codefresh installer, is taking care of all needed dependencies internally by deploying the respective services (mongo, redis etc) on its own.
+
+You might want however to use your own existing options if you already have those services up and running externally.
+
+### Configuring an external Postgres database
+
+It is possible to configure Codefresh to work with your existing Postgres database service, if you don't want to use the default one as provided by the Codefresh installer.
+
+#### Configuration steps
+
+All the configuration comes down to putting a set of correct values into your Codefresh configuration file `config.yaml`, which is present in `your/stage-dir/codefresh` directory. During the installation, Codefresh will run a seed job, using the values described in the following steps:
+
+1. Specify a user name `global.postgresSeedJob.user` and password `global.postgresSeedJob.password` for a seed job. This must be a privileged user allowed to create databases and roles. It will be used only by the seed job to create the needed database and a user.
+2. Specify a user name `global.postgresUser` and password `global.postgresPassword` to be used by Codefresh installation. A user with the name and password will be created by the seed job and granted with required privileges to access the created database.
+3. Specify a database name `global.postgresDatabase` to be created by the seed job and used by Codefresh installation.
+4. Specify `global.postgresHostname` and optionally `global.postgresPort` (`5432` is a default value).
+5. Disable the postgres subchart installation with the `postgresql.enabled: false` value, because it is not needed in this case.
+
+
+Below is an example of the relevant piece of `config.yaml`:
+
+```yaml
+global:
+ postgresSeedJob:
+ user: postgres
+ password: zDyGp79XyZEqLq7V
+ postgresUser: cf_user
+ postgresPassword: fJTFJMGV7sg5E4Bj
+ postgresDatabase: codefresh
+ postgresHostname: my-postgres.ccjog7pqzunf.us-west-2.rds.amazonaws.com
+ postgresPort: 5432
+
+postgresql:
+ enabled: false #disable default postgresql subchart installation
+```
+#### Running the seed job manually
+
+If you prefer running the seed job manually, you can do it by using a script present in `your/stage-dir/codefresh/addons/seed-scripts` directory named `postgres-seed.sh`. The script takes the following set of variables that you need to have set before running it:
+
+```shell
+export POSTGRES_SEED_USER="postgres"
+export POSTGRES_SEED_PASSWORD="zDyGp79XyZEqLq7V"
+export POSTGRES_USER="cf_user"
+export POSTGRES_PASSWORD="fJTFJMGV7sg5E4Bj"
+export POSTGRES_DATABASE="codefresh"
+export POSTGRES_HOST="my-postgres.ccjog7pqzunf.us-west-2.rds.amazonaws.com"
+export POSTGRES_PORT="5432"
+```
+The variables have the same meaning as the configuration values described in the previous section about Postgres.
+
+However you **still need to specify a set of values** in the Codefresh config file as described in the section above, but with the whole **`postgresSeedJob` section omitted**, like this:
+
+```yaml
+global:
+ postgresUser: cf_user
+ postgresPassword: fJTFJMGV7sg5E4Bj
+ postgresDatabase: codefresh
+ postgresHostname: my-postgresql.prod.svc.cluster.local
+ postgresPort: 5432
+
+postgresql:
+ enabled: false #disable default postgresql subchart installation
+```
+
+### Configuring an external MongoDB
+
+Codefresh recommends to use the Bitnami MongoDB [chart](https://github.com/bitnami/charts/tree/master/bitnami/mongodb) as a Mongo database. The supported version of Mongo is 4.2.x
+
+To configure Codefresh on-premises to use an external Mongo service one needs to provide the following values in `config.yaml`:
+
+- **mongo connection string** - `mongoURI`. This string will be used by all of the services to communicate with mongo. Codefresh will automatically create and add a user with "ReadWrite" permissions to all of the created databases with the username and password from the URI. Optionally, automatic user addition can be disabled - `mongoSkipUserCreation`, in order to use already existing user. In such a case the existing user must have **ReadWrite** permissions to all of newly created databases
+Codefresh does not support [DNS Seedlist Connection Format](https://docs.mongodb.com/manual/reference/connection-string/#connections-dns-seedlist) at the moment, use the [Standard Connection Format](https://docs.mongodb.com/manual/reference/connection-string/#connections-standard-connection-string-format) instead.
+- mongo **root user** name and **password** - `mongodbRootUser`, `mongodbRootPassword`. The privileged user will be used by Codefresh only during installation for seed jobs and for automatic user addition. After installation, credentials from the provided mongo URI will be used. Mongo root user must have permissions to create users.
+
+See the [Mongo required Access](https://docs.mongodb.com/manual/reference/method/db.createUser/#required-access) for more details.
+
+Here is an example of all the related values:
+
+```yaml
+global:
+ mongodbRootUser:
+ `global.mongoCaCert` - CA certificate file path (in kcfi init directory)
+ `global.mongoCaKey` - CA certificate private key file path (in kcfi init directory) + +`config.yaml` example: +```yaml +global: + mongodbRootUser: root + mongodbRootPassword: WOIqcSwr0y + mongoURI: mongodb://my-mongodb.prod.svc.cluster.local/?ssl=true&authMechanism=MONGODB-X509&authSource=$external + mongoSkipUserCreation: true + mongoDeploy: false # disables deployment of internal mongo service + + mongoTLS: true #enable MongoDB TLS support + mongoCaCert: mongodb-ca/ca-cert.pem + mongoCaKey: mongodb-ca/ca-key.pem + + ### for OfflineLogging feature + runtimeMongoURI: mongodb://my-mongodb.prod.svc.cluster.local/?ssl=true&authMechanism=MONGODB-X509&authSource=$external + +### for OfflineLogging feature +cfapi: + env: + RUNTIME_MONGO_TLS: "true" + RUNTIME_MONGO_TLS_VALIDATE: "true" # 'false' if self-signed certificate to avoid x509 errors + +## set MONGO_MTLS_VALIDATE to `false` if self-signed certificate to avoid x509 errors +cluster-providers: + env: + MONGO_MTLS_VALIDATE: "false" + +k8s-monitor: + env: + MONGO_MTLS_VALIDATE: "false" + +mongo: + enabled: false #disable default mongodb subchart installation + ``` + + >Perform an upgarde:
+ >`kcfi deploy -c config.yaml --debug` + +### Configure an external Redis service +Codefresh recommends to use the Bitnami Redis [chart](https://github.com/bitnami/charts/tree/master/bitnami/redis) as a Redis store. + +**Limitations** + +Codefresh does not support secure connection to Redis (TLS) and AUTH username extension. + +**Configuration** + +To configure Codefresh to use an external Redis service, add the following parameters to your `config.yaml`: + +`config.yaml` example: +```yaml +global: + redisUrl: my-redis.prod.svc.cluster.local + redisPort: 6379 + redisPassword: 6oOhHI8fI5 + + runtimeRedisHost: my-redis.prod.svc.cluster.local + runtimeRedisPassword: 6oOhHI8fI5 + runtimeRedisPort: 6379 + runtimeRedisDb: 2 + +redis: + enabled: false #disable default redis subchart installation +``` + +Where `redis*` - are for the main Redis storage, and `runtimeRedis*` - for storage is used to store pipeline logs in case of `OfflineLogging` feature is turned on. In most cases the host value is the same for these two values. + + +### Configuring an external RabbitMQ service + +Codefresh recommends to use the Bitnami RabbitMQ [chart](https://github.com/bitnami/charts/tree/master/bitnami/rabbitmq) as a RabbitMQ service. + +To use an external RabbitMQ service instead of the local helm chart, add the following values to the __config.yaml__: + +```yaml +rabbitmq: + enabled: false + +global: + rabbitmqUsername:
**Down:** Node resource allocations is low | On GKE we can turn on/off autoscaler and configure min/max per node group can be also installed separately | Listens on pending pods for scale up and node allocations for scaledown. Should have permissions to call cloud api. Considers pod affinity, pdb, storage, special annotations | +| [Horizontal Pod Autoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/) | replicas on deployments or StatefulSets | metrics value thresholds defined in HPA object | part of Kubernetes controller | Controller gets metrics from "metrics.k8s.io/v1beta1" , "custom.metrics.k8s.io/v1beta1", "external.metrics.k8s.io/v1beta1" requires [metrics-server](https://github.com/kubernetes-sigs/metrics-server) and custom metrics adapters ([prometheus-adapter](https://github.com/kubernetes-sigs/prometheus-adapter), [stackdriver-adapter](https://github.com/GoogleCloudPlatform/k8s-stackdriver/tree/master/custom-metrics-stackdriver-adapter)) to listen on this API (see note (1) below) and adjusts deployment or sts replicas according to definitions in HorizontalPodAutocaler
There are v1 and beta api versions for HorizontalPodAutocaler:
[v1](https://github.com/kubernetes/api/blob/master/autoscaling/v1/types.go) - supports for resource metrics (cpu, memory) - `kubect get hpa`
[v2beta2](https://github.com/kubernetes/api/blob/master/autoscaling/v2beta2/types.go) and [v2beta1](https://github.com/kubernetes/api/blob/master/autoscaling/v2beta1/types.go) - supports for both resource and custom metrics - `kubectl get hpa.v2beta2.autoscaling` **The metric value should decrease on adding new pods.**
*Wrong metrics Example:* request rate
*Right metrics Example:* average request rate per pod | + +Note (1) +``` +kubectl get apiservices | awk 'NR==1 || $1 ~ "metrics"' +NAME SERVICE AVAILABLE AGE +v1beta1.custom.metrics.k8s.io monitoring/prom-adapter-prometheus-adapter True 60d +v1beta1.metrics.k8s.io kube-system/metrics-server True 84d +``` + + +**Implementation in Codefresh** + +* Default “Enable Autoscaling” settings for GKE +* Using [prometheus-adapter](https://github.com/kubernetes-sigs/prometheus-adapter) with custom metrics + +We define HPA for cfapi and pipeline-manager services + +**CFapi HPA object** + +It's based on three metrics (HPA controller scales of only one of the targetValue reached): + +``` +kubectl get hpa.v2beta1.autoscaling cf-cfapi -oyaml +``` + +{% highlight yaml %} +{% raw %} +apiVersion: autoscaling/v2beta1 +kind: HorizontalPodAutoscaler +metadata: + annotations: + meta.helm.sh/release-name: cf + meta.helm.sh/release-namespace: default + labels: + app.kubernetes.io/managed-by: Helm + name: cf-cfapi + namespace: default +spec: + maxReplicas: 16 + metrics: + - object: + metricName: requests_per_pod + target: + apiVersion: v1 + kind: Service + name: cf-cfapi + targetValue: "10" + type: Object + - object: + metricName: cpu_usage_avg + target: + apiVersion: apps/v1 + kind: Deployment + name: cf-cfapi-base + targetValue: "1" + type: Object + - object: + metricName: memory_working_set_bytes_avg + target: + apiVersion: apps/v1 + kind: Deployment + name: cf-cfapi-base + targetValue: 3G + type: Object + minReplicas: 2 + scaleTargetRef: + apiVersion: apps/v1 + kind: Deployment + name: cf-cfapi-base +{% endraw%} +{% endhighlight %} + +* `requests_per_pod` is based on `rate(nginx_ingress_controller_requests)` metric ingested from nginx-ingress-controller +* `cpu_usage_avg` based on cadvisor (from kubelet) rate `(rate(container_cpu_user_seconds_total)` +* `memory_working_set_bytes_avg` based on cadvisor `container_memory_working_set_bytes` + +**pipeline-manager HPA** + +based on `cpu_usage_avg` + +{% highlight yaml %} +{% raw %} +apiVersion: autoscaling/v2beta1 +kind: HorizontalPodAutoscaler +metadata: + annotations: + meta.helm.sh/release-name: cf + meta.helm.sh/release-namespace: default + labels: + app.kubernetes.io/managed-by: Helm + name: cf-pipeline-manager +spec: + maxReplicas: 8 + metrics: + - object: + metricName: cpu_usage_avg + target: + apiVersion: apps/v1 + kind: Deployment + name: cf-pipeline-manager-base + targetValue: 400m + type: Object + minReplicas: 2 + scaleTargetRef: + apiVersion: apps/v1 + kind: Deployment + name: cf-pipeline-manager-base +{% endraw%} +{% endhighlight %} + +**prometheus-adapter configuration** + +Reference: [https://github.com/DirectXMan12/k8s-prometheus-adapter/blob/master/docs/config.md](https://github.com/DirectXMan12/k8s-prometheus-adapter/blob/master/docs/config.md +) + +{% highlight yaml %} +{% raw %} +Rules: + - metricsQuery: | + kube_service_info{<<.LabelMatchers>>} * on() group_right(service) + (sum(rate(nginx_ingress_controller_requests{<<.LabelMatchers>>}[2m])) + / on() kube_deployment_spec_replicas{deployment='<
+Runtime components' (engine and dind) configuration is determined by the `runner init` command.
+The `helm install` command can only control the configuration of `runner`, `dind-volume-provisioner` and `lv-monitor` components. + +## Using the Codefresh Runner + +Once installed, the Runner is fully automated. It polls the Codefresh SAAS (by default every 3 seconds) on its own and automatically creates all resources needed for running pipelines. + +Once installation is complete, you should see the cluster of the runner as a new [Runtime environment](https://g.codefresh.io/account-admin/account-conf/runtime-environments) in Codefresh in your *Account Settings*, in the respective tab. + +{% include image.html + lightbox="true" + file="/images/administration/runner/runtime-environments.png" + url="/images/administration/runner/runtime-environments.png" + alt="Available runtime environments" + caption="Available runtime environments" + max-width="60%" + %} + +If you have multiple environments available, you can change the default (shown with a thin blue border) by clicking on the 3 dot menu on the right of each environment. The Codefresh runner installer comes with a `set-default` option that is automatically set by default in the new runtime environment. + +You can even override the runtime environment for a specific pipeline by specifying in the respective section in the [pipeline settings]({{site.baseurl}}/docs/configure-ci-cd-pipeline/pipelines/). + +{% include image.html + lightbox="true" + file="/images/administration/runner/environment-per-pipeline.png" + url="/images/administration/runner/environment-per-pipeline.png" + alt="Running a pipeline on a specific environment" + caption="Running a pipeline on a specific environment" + max-width="60%" + %} + +## Checking the Runner + +Once installed, the runner is a normal Kubernetes application like all other applications. You can use your existing tools to monitor it. + +Only the runner pod is long living inside your cluster. All other components (such as the engine) are short lived and exist only during pipeline builds. +You can always see what the Runner is doing by listing the resources inside the namespace you chose during installation: + +```shell +$ kubectl get pods -n codefresh-runtime +NAME READY STATUS RESTARTS AGE +dind-5ee7577017ef40908b784388 1/1 Running 0 22s +dind-lv-monitor-runner-hn64g 1/1 Running 0 3d +dind-lv-monitor-runner-pj84r 1/1 Running 0 3d +dind-lv-monitor-runner-v2lhc 1/1 Running 0 3d +dind-volume-provisioner-runner-64994bbb84-lgg7v 1/1 Running 0 3d +engine-5ee7577017ef40908b784388 1/1 Running 0 22s +monitor-648b4778bd-tvzcr 1/1 Running 0 3d +runner-5d549f8bc5-7h5rc 1/1 Running 0 3d +``` + +In the same manner you can list secrets, config-maps, logs, volumes etc. for the Codefresh builds. + +## Uninstall the Codefresh Runner + +You can uninstall the Codefresh runner from your cluster by running: + +```shell +codefresh runner delete +``` + +A wizard, similar to the installation wizard, will ask you questions regarding your cluster before finishing with the removal. + +Like the installation wizard, you can pass the additional options in advance as command line parameters (see `--help` output): +```shell +codefresh runner delete --help +``` + + + +## Runner architecture overview + +{% include image.html + lightbox="true" + file="/images/administration/runner/codefresh_runner.png" + url="/images/administration/runner/codefresh_runner.png" + alt="Codefresh Runner architecture overview" + caption="Codefresh Runner architecture overview" + max-width="100%" + %} + + +1. [Runtime-Environment specification]({{site.baseurl}}/docs/administration/codefresh-runner/) defines engine and dind pods spec and PVC parameters. +2. Runner pod (Agent) pulls tasks (Builds) from Codefresh API every 3 seconds. +3. Once the agent receives build task (either Manual run build or Webhook triggered build) it calls k8s API to create engine/dind pods and PVC object. +4. Volume Provisioner listens for PVC events (create) and based on StorageClass definition it creates PV object with the corresponding underlying volume backend (ebs/gcedisk/local). +5. During the build, each step (clone/build/push/freestyle/composition) is represented as docker container inside dind (docker-in-docker) pod. Shared Volume (`/codefresh/volume`) is represented as docker volume and mounted to every step (docker containers). PV mount point inside dind pod is `/var/lib/docker`. +6. Engine pod controls dind pod. It deserializes pipeline yaml to docker API calls, terminates dind after build has been finished or per user request (sigterm). +7. `dind-lv-monitor` DaemonSet OR `dind-volume-cleanup` CronJob are part of [Runtime Cleaner]({{site.baseurl}}/docs/administration/codefresh-runner/#runtime-cleaners), `app-proxy` Deployment and Ingress are described in the [next section]({{site.baseurl}}/docs/administration/codefresh-runner/#app-proxy-installation), `monitor` Deployment is for [Kubernetes Dashboard]({{site.baseurl}}/docs/deploy-to-kubernetes/manage-kubernetes/). + +## App Proxy installation + +The App Proxy is an **optional** component of the runner that is mainly used when the git provider server is installed on-premises behind the firewall. The App Proxy provides the following features once installed: + +* Enables you to automatically create webhooks for Git in the Codefresh UI (same as the SAAS experience) +* Sends commit status information back to your Git provider (same as the SAAS experience) +* Makes all Git Operations in the GUI work exactly like the SAAS installation of Codefresh + +The requirements for the App proxy is a Kubernetes cluster that: + +1. has already the Codefresh runner installed +1. has an active [ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress/) +1. allows incoming connections from the VPC/VPN where users are browsing the Codefresh UI. The ingress connection **must** have a hostname assigned for this route and **must** be configured to perform SSL termination + +>Currently the App-proxy works only for Github (SAAS and on-prem versions), Gitlab (SAAS and on-prem versions) and Bitbucket server. + +Here is the architecture of the app-proxy: + +{% include image.html + lightbox="true" + file="/images/administration/runner/app-proxy-architecture.png" + url="/images/administration/runner/app-proxy-architecture.png" + alt="How App Proxy and the Codefresh runner work together" + caption="How App Proxy and the Codefresh runner work together" + max-width="80%" + %} + +Basically when a Git GET operation takes place, the Codefresh UI will contact the app-proxy (if it is present) and it will route the request to the backing Git provider. The confidential Git information never leaves the firewall premises and the connection between the browser and the ingress is SSL/HTTPS. + +The app-proxy has to work over HTTPS and by default it will use the ingress controller to do its SSL termination. Therefore, the ingress controller will need to be configured to perform SSL termination. Check the documentation of your ingress controller (for example [nginx ingress](https://kubernetes.github.io/ingress-nginx/examples/tls-termination/)). This means that the app-proxy does not compromise security in any way. + +To install the app-proxy on a Kubernetes cluster that already has a Codefresh runner use the following command: + +```shell +codefresh install app-proxy --host=
+`dind-volume-provisioner-role.json` +```json +{ + "Name": "CodefreshDindVolumeProvisioner", + "Description": "Perform create/delete/get disks", + "IsCustom": true, + "Actions": [ + "Microsoft.Compute/disks/read", + "Microsoft.Compute/disks/write", + "Microsoft.Compute/disks/delete" + + ], + "AssignableScopes": ["/subscriptions/
Tip: To check the server version, run:
kubectl version --short.{:/}| +| Ingress controller| Configured on Kubernetes cluster and exposed from the cluster. {::nomarkdown}
Supported and tested ingress controllers include: