diff --git a/_data/home-content.yml b/_data/home-content.yml index 18f73ad1..319bcdcb 100644 --- a/_data/home-content.yml +++ b/_data/home-content.yml @@ -21,7 +21,7 @@ icon: images/home-icons/client.svg url: '' links: - - title: Codefresh CLI + - title: Download/upgrade Codefresh CLI localurl: /docs/clients/csdp-cli/ diff --git a/_data/nav.yml b/_data/nav.yml index cfb2f70a..cc7e3654 100644 --- a/_data/nav.yml +++ b/_data/nav.yml @@ -38,7 +38,7 @@ - title: Clients url: "/clients" pages: - - title: Download CLI + - title: Download/upgrade Codefresh CLI url: "/csdp-cli" diff --git a/_docs/clients/csdp-cli.md b/_docs/clients/csdp-cli.md index 2882c367..7b23654f 100644 --- a/_docs/clients/csdp-cli.md +++ b/_docs/clients/csdp-cli.md @@ -1,13 +1,12 @@ --- -title: "Download CLI" +title: "Download/upgrade Codefresh CLI" description: "" group: clients toc: true --- -You need the Codefresh CLI to install Codefresh runtimes. -* For the initial download, you also need to generate the API key and create the API authentication context, all from the UI. -* Subsequent downloads for upgrade purposes require you to only run the download command, using existing API credentials. +You need the Codefresh CLI to install Codefresh runtimes. For the initial download, you also need to generate the API key and create the API authentication context, all from the UI. +If upgrades are needed, the CLI notifies you through a banner, and you can use the existing API credentials. ### Download Codefresh CLI Downloading the Codefresh CLI requires you to select the download mode and OS, generate an API key, and authentication context. @@ -24,24 +23,37 @@ Downloading the Codefresh CLI requires you to select the download mode and OS, g 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%" + max-width="50%" %} ### Upgrade Codefresh CLI -Upgrade the CLI to the latest version to prevent installation errors. -1. Check the version of the CLI you have installed: - `cf version` -1. Compare with the [latest version](https://github.com/codefresh-io/cli-v2/releases){:target="\_blank"} released by Codefresh. -1. Select and run the appropriate command: - -{: .table .table-bordered .table-hover} -| Download 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`| +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="50%" + %} + +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 [Set up hosted (Hosted GitOps) environment]({{site.baseurl}}/docs/runtime/hosted-runtime) diff --git a/_docs/getting-started/architecture.md b/_docs/getting-started/architecture.md index d2d8a211..d8a35aeb 100644 --- a/_docs/getting-started/architecture.md +++ b/_docs/getting-started/architecture.md @@ -81,6 +81,20 @@ In the hosted environment, the Codefresh Runtime is installed on a K8s cluster m max-width="100%" %} +#### Tunnel-based hybrid runtime architecture +Tunnel-based hybrid runtimes use tunneling instead of ingress controllers to control communication between the Codefresh Runtime in the customer cluster and the Codefresh Platform. Tunnel-based, ingress-less, runtimes are optimal when the cluster with the Codefresh 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 runtime architecture Ingress-based runtimes use ingress controllers to control communication between the Codefresh Runtime in the customer cluster and the Codefresh Platform. Ingress-based runtimes are optimal when the cluster with the Codefresh Runtime is exposed to the internet. @@ -96,20 +110,6 @@ Ingress-based runtimes use ingress controllers to control communication between max-width="100%" %} -#### Tunnel-based hybrid runtime architecture -Tunnel-based hybrid runtimes use tunneling instead of ingress controllers to control communication between the Codefresh Runtime in the customer cluster and the Codefresh Platform. Tunnel-based, ingress-less, runtimes are optimal when the cluster with the Codefresh 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%" -%} - - #### Codefresh Application Proxy The Codefresh Application Proxy (App-Proxy) functions as the Codefresh agent, and is deployed as a service in the Codefresh Runtime. diff --git a/_docs/runtime/installation.md b/_docs/runtime/installation.md index 2d76307c..09e96ce0 100644 --- a/_docs/runtime/installation.md +++ b/_docs/runtime/installation.md @@ -21,8 +21,8 @@ If Bitbucker Server is your Git provider, you must also select the specific serv 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. +1. [Installing the Codefresh CLI](#install-the-codefresh-cli) +2. [Installing the hybrid runtime](#install-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. @@ -32,6 +32,62 @@ There are two parts to installing a hybrid runtime: See also [Codefresh architecture]({{site.baseurl}}/docs/getting-started/architecture). + + +### 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 + +{::nomarkdown} +
+{:/} + +**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 provider]({{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) +* 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}
{:/} @@ -69,26 +125,31 @@ The cluster defined as the default for `kubectl`. If you have more than one Kube * 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/getting-started/architecture/#tunnel-based-hybrid-runtime-architecture), for runtimes without ingress controllers. This is the default. +* [Ingress-based]({{site.baseurl}}/docs/getting-started/architecture/#ingress-based-hybrid-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 (ingress-less) runtime flags](#tunnel-based-ingress-less-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 (ingress-less) runtime flags -These flags are required to install the runtime without an ingress controller. - -**Access mode** -Required. - -The access mode for tunnel-based runtimes, the tunnel mode. - -* CLI wizard and Silent install: Add the flag, `--access-mode`, and define `tunnel` as the value. - - **IP allowlist** Optional. @@ -104,7 +165,7 @@ When omitted, all incoming requests are authenticated regardless of the IPs from {:/} #### Ingress controller flags - +Ingress controller flags are required for ingress-based runtimes. For **Skip ingress** Required, if you are using an unsupported ingress controller. @@ -126,6 +187,7 @@ The IP address or host name of the ingress controller component. > 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** +Optional. 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. @@ -148,9 +210,8 @@ For both CLI wizard and Silent install: #### 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. +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 also used for all the other runtimes in the same account. You can define any of the following Git providers: * GitHub: @@ -163,11 +224,15 @@ You can define any of the following Git providers: * [Bitbucket Cloud](#bitbucket-cloud) * [Bitbucket Server](#bitbucket-server) -{::nomarkdown} -
-{:/} +
+ + +Codefresh tries to identify the Git provider from the repository URL you provide. +* CLI wizard: If not GitHub, you are prompted to select the Git provider from the list. +* Silent install: Pass the flags required per provider, as described in the sections below. +
##### 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. @@ -197,13 +262,14 @@ where: ##### GitHub Enterprise +* CLI Wizard: Select the Git provider from the list provided + > 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 ` +`--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. @@ -228,10 +294,9 @@ where: > 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 ` +`--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. @@ -265,10 +330,9 @@ where: > 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 ` +`--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. @@ -299,10 +363,9 @@ where: > 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 ` +`--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. @@ -332,10 +395,9 @@ where: > 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 ` +`--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. @@ -374,53 +436,7 @@ For _on-premises installations_, if the Ingress controller does not have a valid {:/} -### 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 provider]({{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} diff --git a/_docs/runtime/monitor-manage-runtimes.md b/_docs/runtime/monitor-manage-runtimes.md index 80020277..06794243 100644 --- a/_docs/runtime/monitor-manage-runtimes.md +++ b/_docs/runtime/monitor-manage-runtimes.md @@ -30,6 +30,7 @@ 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) +* [Upgrade Codefresh CLI](#upgrade-codefresh-cli) * [Uninstall provisioned runtimes](#uninstall-provisioned-runtimes) * [Update Git tokens for runtimes](#update-git-tokens-for-runtimes) @@ -99,6 +100,34 @@ Here is a description of the information in the Topology view. |**Search and View options** | {::nomarkdown}
  • 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.
{:/}| +### Upgrade Codefresh 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`. + ### (Hybrid) Upgrade provisioned runtimes @@ -113,8 +142,8 @@ If you have managed clusters for the hybrid runtime, upgrading the runtime autom **Before you begin** For both silent or CLI-wizard based upgrades, make sure you have: -* The latest version of the Codefresh CLI - Run `cf version` to see your version and [click here](https://github.com/codefresh-io/cli-v2/releases){:target="\_blank"} to compare with the latest CLI version. +* The [latest version of the Codefresh CLI](#upgrade-codefresh-cli) + * A valid Git token with [the required scopes]({{site.baseurl}}/docs/reference/git-tokens) **Silent upgrade** @@ -178,9 +207,9 @@ For both silent or CLI-wizard based upgrades, make sure you have: -