From 55a1494eee5b3d0a23b62b6948455039495be6de Mon Sep 17 00:00:00 2001 From: Yoshiki Fujikane Date: Tue, 6 Feb 2024 12:27:32 +0900 Subject: [PATCH] Regen docs for v0.46.0 Signed-off-by: Yoshiki Fujikane --- .../install-piped/installing-on-fargate.md | 6 +- .../en/docs-v0.46.x/quickstart/_index.md | 1 + .../customizing-deployment/script-run.md | 75 ++++++++++++++++--- 3 files changed, 70 insertions(+), 12 deletions(-) diff --git a/docs/content/en/docs-v0.46.x/installation/install-piped/installing-on-fargate.md b/docs/content/en/docs-v0.46.x/installation/install-piped/installing-on-fargate.md index bc6cee74fc..32031b7fa6 100644 --- a/docs/content/en/docs-v0.46.x/installation/install-piped/installing-on-fargate.md +++ b/docs/content/en/docs-v0.46.x/installation/install-piped/installing-on-fargate.md @@ -63,10 +63,10 @@ description: > See [ConfigurationReference](../../../user-guide/managing-piped/configuration-reference/) for the full configuration. -- Store the above configuration data to AWS to enable using it while creating piped task. Both [AWS SecretManager](https://aws.amazon.com/secrets-manager/) and [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) are available to address this task. +- Store the above configuration data to AWS to enable using it while creating piped task. Both [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) and [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) are available to address this task. {{< tabpane >}} - {{< tab lang="bash" header="Store in AWS SecretManager" >}} + {{< tab lang="bash" header="Store in AWS Secrets Manager" >}} aws secretsmanager create-secret --name PipedConfig \ --description "Configuration of piped running as ECS Fargate task" \ --secret-string `base64 piped-config.yaml` @@ -79,7 +79,7 @@ See [ConfigurationReference](../../../user-guide/managing-piped/configuration-re {{< /tab >}} {{< /tabpane >}} -- Prepare task definition for your piped task. Basically, you can just define your piped TaskDefinition as normal TaskDefinition, the only thing that needs to be beware is, in case you used [AWS SecretManager](https://aws.amazon.com/secrets-manager/) to store piped configuration, to enable your piped accesses it's configuration we created as a secret on above, you need to add `secretsmanager:GetSecretValue` policy to your piped task `executionRole`. Read more in [Required IAM permissions for Amazon ECS secrets](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data-secrets.html). +- Prepare task definition for your piped task. Basically, you can just define your piped TaskDefinition as normal TaskDefinition, the only thing that needs to be beware is, in case you used [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) to store piped configuration, to enable your piped accesses it's configuration we created as a secret on above, you need to add `secretsmanager:GetSecretValue` policy to your piped task `executionRole`. Read more in [Required IAM permissions for Amazon ECS secrets](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data-secrets.html). A sample TaskDefinition for Piped as follows diff --git a/docs/content/en/docs-v0.46.x/quickstart/_index.md b/docs/content/en/docs-v0.46.x/quickstart/_index.md index 4ee7296907..3021a7bd82 100644 --- a/docs/content/en/docs-v0.46.x/quickstart/_index.md +++ b/docs/content/en/docs-v0.46.x/quickstart/_index.md @@ -13,6 +13,7 @@ Note: It's not required to install the PipeCD control plane to the cluster where ### Prerequisites - Having a Kubernetes cluster and connect to it via [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). - Forked the [Examples](https://github.com/pipe-cd/examples) repository +- Prepare for authentication to [GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry). ### 1. Installing PipeCD in quickstart mode diff --git a/docs/content/en/docs-v0.46.x/user-guide/managing-application/customizing-deployment/script-run.md b/docs/content/en/docs-v0.46.x/user-guide/managing-application/customizing-deployment/script-run.md index cade2f8439..aa01c4949a 100644 --- a/docs/content/en/docs-v0.46.x/user-guide/managing-application/customizing-deployment/script-run.md +++ b/docs/content/en/docs-v0.46.x/user-guide/managing-application/customizing-deployment/script-run.md @@ -8,12 +8,11 @@ description: > `SCRIPT_RUN` stage is one stage in the pipeline and you can execute any commands. -> Note: This feature is at the alpha status. +> Note: This feature is at the alpha status and currently only for the application kind of KubernetesApp. ## How to configure SCRIPT_RUN stage Add a `SCRIPT_RUN` to your pipeline and write commands. -The commands run in the directory where this application configuration file exists. ```yaml apiVersion: pipecd.dev/v1beta1 @@ -49,19 +48,77 @@ spec: sleep 10 ``` +You can define the command as `run`. +Also, if you want to some values as variables, you can define them as `env`. + +The commands run in the directory where this application configuration file exists. + ![](/images/script-run.png) -Note: -1. You can use `SCRIPT_RUN` stage with any current supporting application kind. +# When to rollback + +You can define the command as `onRollback` to execute when to rollback similar to `run`. +Execute the command to rollback SCRIPT_RUN to the point where the deployment was canceled or failed. + +```yaml +apiVersion: pipecd.dev/v1beta1 +kind: KubernetesApp +spec: + name: canary-with-script-run + labels: + env: example + team: product + pipeline: + stages: + - name: K8S_CANARY_ROLLOUT + with: + replicas: 10% + - name: WAIT + with: + duration: 10s + - name: SCRIPT_RUN + with: + env: + MSG: "execute script1" + R_MSG: "rollback script1" + run: | + echo $MSG + sleep 10 + onRollback: | + echo $R_MSG + sleep 10 + - name: K8S_PRIMARY_ROLLOUT + - name: K8S_CANARY_CLEAN +``` + +![](/images/script-run-onRollback.png) + +The command defined as `onRollback` is executed as `SCRIPT_RUN_ROLLBACK` stage after each `ROLLBACK` stage. +When there are multiple SCRIPT_RUN stages, they are executed in the same order as SCRIPT_RUN on the pipeline. +Also, only for the executed SCRIPT_RUNs are rollbacked. + +For example, consider when deployment proceeds in the following order from 1 to 7. +``` +1. K8S_CANARY_ROLLOUT +2. WAIT +3. SCRIPT_RUN +4. K8S_PRIMARY_ROLLOUT +5. SCRIPT_RUN +6. K8S_CANARY_CLEAN +7. SCRIPT_RUN +``` + +Then +- If 3 is canceled or fails while running, only SCRIPT_RUN of 3 will be rollbacked. +- If 4 is canceled or fails while running, only SCRIPT_RUN of 3 will be rollbacked. +- If 6 is canceled or fails while running, only SCRIPT_RUNs 3 and 5 will be rollbacked. The order of executing is 3 -> 5. + +# Note +1. You can use `SCRIPT_RUN` stage with only the application kind of `KubernetesApp`. Soon we will implement it. for other application kinds. 2. The public piped image available in PipeCD main repo (ref: [Dockerfile](https://github.com/pipe-cd/pipecd/blob/master/cmd/piped/Dockerfile)) is based on [alpine](https://hub.docker.com/_/alpine/) and only has a few UNIX command available (ref: [piped-base Dockerfile](https://github.com/pipe-cd/pipecd/blob/master/tool/piped-base/Dockerfile)). If you want to use your commands, you can: - Prepare your own environment container image then add [piped binary](https://github.com/pipe-cd/pipecd/releases) to it. - Build your own container image based on `ghcr.io/pipe-cd/piped` image. - Manually update your running piped container (not recommended). - -# When to rollback - -Even if a rollback occurs, the command will not be executed again. -In the near future, we are considering the ability to run this command also on rollback.