From fba1bf0f4435dab325b0caac9c17c1a7253dbaf9 Mon Sep 17 00:00:00 2001 From: bogdan-volynets Date: Thu, 12 Jan 2023 18:31:54 +0200 Subject: [PATCH 1/5] wip --- _data/nav.yml | 39 ++-- .../create-ci-pipeline/test-sub-page.md | 184 ++++++++++++++++++ .../create-ci-pipeline/test-sub-page2.md | 184 ++++++++++++++++++ _includes/docs-sidebar.html.twig | 33 +++- 4 files changed, 422 insertions(+), 18 deletions(-) create mode 100644 _docs/getting-started/quick-start/create-ci-pipeline/test-sub-page.md create mode 100644 _docs/getting-started/quick-start/create-ci-pipeline/test-sub-page2.md diff --git a/_data/nav.yml b/_data/nav.yml index cc7e36544..9703b4194 100644 --- a/_data/nav.yml +++ b/_data/nav.yml @@ -13,7 +13,7 @@ - title: Install a hybrid runtime url: "/runtime" - title: Create an application - url: "/create-app-ui" + url: "/create-app-ui" - title: Create and commit resources for application url: "/create-app-specs" - title: Update the image tag for application @@ -22,8 +22,13 @@ url: "/hello-world" - title: Create a basic CI delivery pipeline url: "/create-ci-pipeline" + sub-pages: + - title: Test sub-page + url: "/test-sub-page" + - title: Test sub-page2 + url: "/test-sub-page2" + - - title: Main concepts url: "/main-concepts" - title: Entity model @@ -56,9 +61,9 @@ - title: Manage provisioned runtimes url: "/monitor-manage-runtimes" - title: Monitor provisioned hybrid runtimes - url: "/monitoring-troubleshooting" + url: "/monitoring-troubleshooting" - title: Add external clusters to runtimes - url: "/managed-cluster" + url: "/managed-cluster" - title: Add Git Sources to runtimes url: "/git-sources" @@ -76,7 +81,7 @@ url: "/sharing-file-system" - title: Nested workflows url: "/nested-workflows" - + - title: Deployment url: "/deployment" @@ -90,7 +95,7 @@ - title: Images in Codefresh url: "/images" - title: Install Argo Rollouts - url: "/install-argo-rollouts" + url: "/install-argo-rollouts" - title: Reports & Insights url: "/reporting" @@ -99,7 +104,7 @@ url: "/home-dashboard" - title: DORA metrics url: "/dora-metrics" - + - title: Image enrichment url: "/integrations" @@ -114,23 +119,23 @@ - title: GitHub Actions url: "/github-actions" - title: Jenkins - url: "/jenkins" + url: "/jenkins" - title: Issue tracking url: "/issue-tracking" - sub-pages: - - title: Jira + sub-pages: + - title: Jira url: "/jira" - title: Container registries url: "/container-registries" - sub-pages: + sub-pages: - title: Amazon ECR - url: "/amazon-ecr" + url: "/amazon-ecr" - title: Docker Hub Registry url: "/dockerhub" - title: GitHub Container Registry url: "/github-cr" - title: JFrog Artifactory - url: "/jfrog" + url: "/jfrog" - title: Quay Registry url: "/quay" @@ -146,7 +151,7 @@ - title: Set up OAuth2 authentication for Git providers url: "/oauth-setup" - title: Authorize access to organizations/projects - url: "/hosted-authorize-orgs" + url: "/hosted-authorize-orgs" - title: Single Sign-On url: "/single-sign-on" sub-pages: @@ -179,10 +184,10 @@ - title: Git tokens url: "/git-tokens" - title: Secrets - url: "/secrets" + url: "/secrets" - title: Shared configuration repo url: "/shared-configuration" - + - title: What's New? url: "/whats-new" pages: @@ -194,7 +199,7 @@ pages: - title: Runtimes url: "/runtime-issues" - + - title: Terms and Privacy Policy url: "/terms-and-privacy-policy" diff --git a/_docs/getting-started/quick-start/create-ci-pipeline/test-sub-page.md b/_docs/getting-started/quick-start/create-ci-pipeline/test-sub-page.md new file mode 100644 index 000000000..bdd80a717 --- /dev/null +++ b/_docs/getting-started/quick-start/create-ci-pipeline/test-sub-page.md @@ -0,0 +1,184 @@ +--- +title: "Test Sub Page" +description: "test sub page desctiption" +toc: true +--- + +Now that you have configured and run the Hello World demo pipeline, let's create a more advanced pipeline. + +For the quick start, you'll create a basic CI Delivery Pipeline in Codefresh. + +The Delivery Pipeline: +* Clones a Git repository +* Builds a docker image using `kaniko` +* Pushes the built image to a Docker Registry +* Runs an example testing step +* Sends the image information to Codefresh + +Our CI pipeline interacts with third-party services such as GitHub and a Docker Registry. You need to first add secrets to the cluster to store the credentials required. + + +### Create a Personal Access Token (PAT) +You must have a PAT to clone the repository. + + +1. Create your PAT (Personal Access Token) with a valid `expiration` date and `scope`. + Scopes: `repo` and `admin-repo.hook` + +{% include +image.html +lightbox="true" +file="/images/getting-started/quick-start/quick-start-git-event-permissions.png" +url="/images/getting-started/quick-start/quick-start-git-event-permissions.png" +alt="GitHub PAT permissions for CI pipeline" +caption="GitHub PAT permissions for CI pipeline" +max-width="30%" +%} + +{:start="2"} +1. Define your PAT and namespace by replacing the values in these commands: + +``` + export GIT_TOKEN=[PAT token] + export NAMESPACE=[Codefresh runtime namespace] +``` + +1. Create a generic Kubernetes secret with your PAT token: + +``` +kubectl create secret generic github-token \ + --from-literal=token=$GIT_TOKEN --dry-run=client \ + --save-config -o yaml | kubectl apply -f - -n $NAMESPACE +``` + +### Create Docker-registry secret +To push the image to a Docker registry, we'll need the credentials on our cluster. + +> The Docker registry secret is different from the general registry secret. + +1. Export the values for the Docker registry's `server`, `username`, `password`, `email`, and `namespace`: + +``` +export DOCKER_REGISTRY_SERVER=[Server] +export DOCKER_USER=[Username] +export DOCKER_PASSWORD=[Password] +export DOCKER_EMAIL=[Email] +export NAMESPACE=[Codefresh runtime namespace] +``` + +{:start="2"} +1. Create the secret: + +``` +kubectl create secret docker-registry \ + --docker-server=$DOCKER_REGISTRY_SERVER \ + --docker-username=$DOCKER_USER \ + --docker-password=$DOCKER_PASSWORD \ + --docker-email=$DOCKER_EMAIL -n $NAMESPACE +``` + +> In the Workflow Template, the Docker registry name defaults to `docker-config`. + + +### Create general registry secret +Create a general registry secret to send the image information to Codefresh. + +1. Export the values for your registry's `username`, `password`, `domain`, and `namespace`: + +``` +export USER=[Username] +export PASSWORD=[Password] +export DOMAIN=[Domain] +export NAMESPACE=[Codefresh runtime namespace] +``` + +{:start="2"} +1. Create the secret: + +``` +kubectl create secret generic registry-creds \ + --from-literal=username=$USER \ + --from-literal=password=$PASSWORD \ + --from-literal=domain=$DOMAIN \ + --dry-run=client --save-config -o yaml | kubectl apply -f - -n $NAMESPACE +``` + +### Create the CI delivery pipeline +Now that you have defined the secrets, create the CI delivery pipeline in Codefresh. + +1. In the UI, go to [Delivery Pipelines](https://g.codefresh.io/2.0/pipelines){:target="\_blank"}. +1. Select **+ Add Delivery Pipeline**. + +{% include +image.html +lightbox="true" +file="/images/getting-started/quick-start/quick-start-new-pipeline.png" +url="/images/getting-started/quick-start/quick-start-new-pipeline.png" +alt="Add Delivery Pipeline panel in Codefresh" +caption="Add Delivery Pipeline panel in Codefresh" +max-width="30%" +%} + +{:start="3"} +1. Enter a name for the delivery pipeline. + The name is created from the names of the sensor and the trigger event for the delivery pipeline. +* **Sensor Name**: The name of the sensor resource, for example, `sensor-cf-ci`. +* **Trigger Name**: The event configured in the sensor to trigger the Workflow Template, for example, `push-cf-ci`. +1. From the list of **Git Sources**, select the Git Source to which to commit the resources for this delivery pipeline. +> Do not select the marketplace Git Source as you cannot commit to it. +If you have multiple runtimes installed, the Git Source you select also determines the runtime that executes the pipeline. +1. Select **Next**. + In the **Configuration** tab, **Workflow Templates** is selected. This is our CI Starter Workflow Template, that builds a Docker image using Kaniko, reports image metadata to Codefresh, and tests the image. +1. Select **Trigger Conditions**. +1. From the **Add** dropdown, select **Git Events**. +1. In the **Git Repository URLs** field, select one or more GitHub repositories to listen to for the selected event. +1. From the **Event** dropdown, select the event, in our case, **Commit pushed**. + Codefresh displays all the **Arguments** available for the selected event. + You can map each argument to a single or combination of predefined variables, which Codefresh automatically maps to the correct path when you commit the changes. Argo Workflow then instantiates the values from the event payload. + + {% include + image.html + lightbox="true" + file="/images/getting-started/quick-start/quick-start-ci-pipeline-arguments.png" + url="/images/getting-started/quick-start/quick-start-ci-pipeline-arguments.png" + alt="Predefined variables for arguments" + caption="Predefined variables for arguments" + max-width="30%" + %} + +In each field, type `$` and from the list of predefined variables, select each of these in turn: + +* **REPO**: Required. The repository to clone during the build step. Select `Repository name`. +* **IMAGE_NAME**: Required. The name for the built image. Enter the name in the format `([docker_url]/[account]/[image_name]`. +* **TAG**: Optional. The tag for the built image. If not defined, uses the default tag `latest`. Enter `1.0`. +* **GIT_REVISION**: Optional. The Git revision to report to Codefresh. Select `Git revision`. +* **GIT_BRANCH**: Optional. The Git branch to report to Codefresh. Select `Git branch`. +* **GIT_COMMIT_URL**: Optional. The Git commit URL to report to Codefresh. Select `Commit url`. +* **GIT_COMMIT_MESSAGE**: Optional. The Git commit message to report to Codefresh. Select `Commit message`. + +You are now ready to commit the delivery pipeline to the Git Source. + +{:start="10"} +1. Select **Apply**, and then **Commit** on the top-right. + The Commit Changes panel shows the files to be committed. +1. Enter the commit message and then select **Commit**. +1. In the **Delivery Pipelines** page to which you are redirected, verify that your pipeline is displayed. + +Behind the scenes, we committed the pipeline to your Git repository and synced the resources to your cluster. +It may take a few seconds for the Git-to-cluster sync to complete, and then your pipeline should be displayed. + +### Trigger the pipeline with a Git commit event +Make a change to a file in the Git repository to trigger the pipeline. + +1. Go to the Git repository selected for the trigger condition. +1. Make a change to any file to get a commit event. +1. In the UI, go back to [Delivery Pipelines](https://g.codefresh.io/2.0/pipelines){:target="\_blank"} to see the new workflow for the pipeline. + +Continue to tweak the pipeline and enhance its capabilities. + + +### What to do next +If you have not created an application in Codefresh, continue with: + +[Create resources for codefresh-guestbook application]({{site.baseurl}}/docs/getting-started/quick-start/create-app-specs) + diff --git a/_docs/getting-started/quick-start/create-ci-pipeline/test-sub-page2.md b/_docs/getting-started/quick-start/create-ci-pipeline/test-sub-page2.md new file mode 100644 index 000000000..26502ae0f --- /dev/null +++ b/_docs/getting-started/quick-start/create-ci-pipeline/test-sub-page2.md @@ -0,0 +1,184 @@ +--- +title: "Test Sub Page2" +description: "test sub page2 desctiption" +toc: true +--- + +Now that you have configured and run the Hello World demo pipeline, let's create a more advanced pipeline. + +For the quick start, you'll create a basic CI Delivery Pipeline in Codefresh. + +The Delivery Pipeline: +* Clones a Git repository +* Builds a docker image using `kaniko` +* Pushes the built image to a Docker Registry +* Runs an example testing step +* Sends the image information to Codefresh + +Our CI pipeline interacts with third-party services such as GitHub and a Docker Registry. You need to first add secrets to the cluster to store the credentials required. + + +### Create a Personal Access Token (PAT) +You must have a PAT to clone the repository. + + +1. Create your PAT (Personal Access Token) with a valid `expiration` date and `scope`. + Scopes: `repo` and `admin-repo.hook` + +{% include +image.html +lightbox="true" +file="/images/getting-started/quick-start/quick-start-git-event-permissions.png" +url="/images/getting-started/quick-start/quick-start-git-event-permissions.png" +alt="GitHub PAT permissions for CI pipeline" +caption="GitHub PAT permissions for CI pipeline" +max-width="30%" +%} + +{:start="2"} +1. Define your PAT and namespace by replacing the values in these commands: + +``` + export GIT_TOKEN=[PAT token] + export NAMESPACE=[Codefresh runtime namespace] +``` + +1. Create a generic Kubernetes secret with your PAT token: + +``` +kubectl create secret generic github-token \ + --from-literal=token=$GIT_TOKEN --dry-run=client \ + --save-config -o yaml | kubectl apply -f - -n $NAMESPACE +``` + +### Create Docker-registry secret +To push the image to a Docker registry, we'll need the credentials on our cluster. + +> The Docker registry secret is different from the general registry secret. + +1. Export the values for the Docker registry's `server`, `username`, `password`, `email`, and `namespace`: + +``` +export DOCKER_REGISTRY_SERVER=[Server] +export DOCKER_USER=[Username] +export DOCKER_PASSWORD=[Password] +export DOCKER_EMAIL=[Email] +export NAMESPACE=[Codefresh runtime namespace] +``` + +{:start="2"} +1. Create the secret: + +``` +kubectl create secret docker-registry \ + --docker-server=$DOCKER_REGISTRY_SERVER \ + --docker-username=$DOCKER_USER \ + --docker-password=$DOCKER_PASSWORD \ + --docker-email=$DOCKER_EMAIL -n $NAMESPACE +``` + +> In the Workflow Template, the Docker registry name defaults to `docker-config`. + + +### Create general registry secret +Create a general registry secret to send the image information to Codefresh. + +1. Export the values for your registry's `username`, `password`, `domain`, and `namespace`: + +``` +export USER=[Username] +export PASSWORD=[Password] +export DOMAIN=[Domain] +export NAMESPACE=[Codefresh runtime namespace] +``` + +{:start="2"} +1. Create the secret: + +``` +kubectl create secret generic registry-creds \ + --from-literal=username=$USER \ + --from-literal=password=$PASSWORD \ + --from-literal=domain=$DOMAIN \ + --dry-run=client --save-config -o yaml | kubectl apply -f - -n $NAMESPACE +``` + +### Create the CI delivery pipeline +Now that you have defined the secrets, create the CI delivery pipeline in Codefresh. + +1. In the UI, go to [Delivery Pipelines](https://g.codefresh.io/2.0/pipelines){:target="\_blank"}. +1. Select **+ Add Delivery Pipeline**. + +{% include +image.html +lightbox="true" +file="/images/getting-started/quick-start/quick-start-new-pipeline.png" +url="/images/getting-started/quick-start/quick-start-new-pipeline.png" +alt="Add Delivery Pipeline panel in Codefresh" +caption="Add Delivery Pipeline panel in Codefresh" +max-width="30%" +%} + +{:start="3"} +1. Enter a name for the delivery pipeline. + The name is created from the names of the sensor and the trigger event for the delivery pipeline. +* **Sensor Name**: The name of the sensor resource, for example, `sensor-cf-ci`. +* **Trigger Name**: The event configured in the sensor to trigger the Workflow Template, for example, `push-cf-ci`. +1. From the list of **Git Sources**, select the Git Source to which to commit the resources for this delivery pipeline. +> Do not select the marketplace Git Source as you cannot commit to it. +If you have multiple runtimes installed, the Git Source you select also determines the runtime that executes the pipeline. +1. Select **Next**. + In the **Configuration** tab, **Workflow Templates** is selected. This is our CI Starter Workflow Template, that builds a Docker image using Kaniko, reports image metadata to Codefresh, and tests the image. +1. Select **Trigger Conditions**. +1. From the **Add** dropdown, select **Git Events**. +1. In the **Git Repository URLs** field, select one or more GitHub repositories to listen to for the selected event. +1. From the **Event** dropdown, select the event, in our case, **Commit pushed**. + Codefresh displays all the **Arguments** available for the selected event. + You can map each argument to a single or combination of predefined variables, which Codefresh automatically maps to the correct path when you commit the changes. Argo Workflow then instantiates the values from the event payload. + + {% include + image.html + lightbox="true" + file="/images/getting-started/quick-start/quick-start-ci-pipeline-arguments.png" + url="/images/getting-started/quick-start/quick-start-ci-pipeline-arguments.png" + alt="Predefined variables for arguments" + caption="Predefined variables for arguments" + max-width="30%" + %} + +In each field, type `$` and from the list of predefined variables, select each of these in turn: + +* **REPO**: Required. The repository to clone during the build step. Select `Repository name`. +* **IMAGE_NAME**: Required. The name for the built image. Enter the name in the format `([docker_url]/[account]/[image_name]`. +* **TAG**: Optional. The tag for the built image. If not defined, uses the default tag `latest`. Enter `1.0`. +* **GIT_REVISION**: Optional. The Git revision to report to Codefresh. Select `Git revision`. +* **GIT_BRANCH**: Optional. The Git branch to report to Codefresh. Select `Git branch`. +* **GIT_COMMIT_URL**: Optional. The Git commit URL to report to Codefresh. Select `Commit url`. +* **GIT_COMMIT_MESSAGE**: Optional. The Git commit message to report to Codefresh. Select `Commit message`. + +You are now ready to commit the delivery pipeline to the Git Source. + +{:start="10"} +1. Select **Apply**, and then **Commit** on the top-right. + The Commit Changes panel shows the files to be committed. +1. Enter the commit message and then select **Commit**. +1. In the **Delivery Pipelines** page to which you are redirected, verify that your pipeline is displayed. + +Behind the scenes, we committed the pipeline to your Git repository and synced the resources to your cluster. +It may take a few seconds for the Git-to-cluster sync to complete, and then your pipeline should be displayed. + +### Trigger the pipeline with a Git commit event +Make a change to a file in the Git repository to trigger the pipeline. + +1. Go to the Git repository selected for the trigger condition. +1. Make a change to any file to get a commit event. +1. In the UI, go back to [Delivery Pipelines](https://g.codefresh.io/2.0/pipelines){:target="\_blank"} to see the new workflow for the pipeline. + +Continue to tweak the pipeline and enhance its capabilities. + + +### What to do next +If you have not created an application in Codefresh, continue with: + +[Create resources for codefresh-guestbook application]({{site.baseurl}}/docs/getting-started/quick-start/create-app-specs) + diff --git a/_includes/docs-sidebar.html.twig b/_includes/docs-sidebar.html.twig index b3235e86e..fbd129f20 100644 --- a/_includes/docs-sidebar.html.twig +++ b/_includes/docs-sidebar.html.twig @@ -10,6 +10,8 @@