Skip to content

Commit

Permalink
Regen docs for v0.46.0
Browse files Browse the repository at this point in the history
Signed-off-by: Yoshiki Fujikane <ffjlabo@gmail.com>
  • Loading branch information
ffjlabo committed Feb 6, 2024
1 parent 0d25f52 commit 55a1494
Show file tree
Hide file tree
Showing 3 changed files with 70 additions and 12 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand All @@ -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

Expand Down
1 change: 1 addition & 0 deletions docs/content/en/docs-v0.46.x/quickstart/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.

0 comments on commit 55a1494

Please sign in to comment.