diff --git a/content/en/_index.md b/content/en/_index.md index fd8913ac..bde976ed 100755 --- a/content/en/_index.md +++ b/content/en/_index.md @@ -24,12 +24,14 @@ description: > Modern software delivery requires sophisticated control of delivery speed and traffic management, as well as integration with external tools and verification processes. Software is rarely deployed to a single environment. Most workflows require promotion from one environment or region to another after meeting constraints such as test executions, manual approvals, CI workflows, and canary analysis. **CD-as-a-Service is a centralized control plane that encapsulates those features and enables deployment to multiple Kubernetes clusters using a secure Kubernetes agent architecture.** CD-as-a-Service supports multi-environment, multi-region app deployments with promotion constraints and advanced deployment strategies, such as canary and blue/green. -## Why you should use CD-as-a-Service +## Why you should use CD-as-a-Service for your Kubernetes deployments * **Native Kubernetes resources:** You create your Kubernetes manifests how you want - manually or by using a tool like Helm or Kustomize. * **Logicless Kubernetes agents in your clusters:** CD-as-a-Service's _Remote Network Agents (RNAs)_ act as simple network relays and provide the CD-as-a-Service control plane with Kubernetes ServiceAccount-based credentials. You don't need to open any ports to grant CD-as-a-Service deployment access to your Kubernetes clusters. * **Centralized business logic:** Deployment logic is encapsulated in the control plane. You get new features immediately without having to worry about edge maintenance -- no Remote Network Agent upgrade campaigns within your organization, no need to manage [Custom Resource Definitions (CRDs)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions). -* **Declarative deployment:** You define your software delivery requirements, traffic shaping, canary analysis, webhooks, and manual approvals in a [declarative deployment configuration file]({{< ref "deployment/overview.md" >}}). +* **Declarative deployment:** You define your software delivery requirements, traffic shaping, canary analysis, + webhooks, and manual approvals in a [declarative deployment configuration file]({{< ref + "deployment/kubernetes/overview.md" >}}). * **Integration with your existing SDLC:** You build and publish your containers where and how you want, whether you use Docker Hub or a private registry that is only accessible in your network. {{< include "cdaas-explained-how.md" >}} diff --git a/content/en/deployment/create-deploy-config.md b/content/en/deployment/create-deploy-config.md index 47c4ea12..a8ed8dcb 100644 --- a/content/en/deployment/create-deploy-config.md +++ b/content/en/deployment/create-deploy-config.md @@ -1,9 +1,7 @@ --- title: Create a Deployment Config File linkTitle: Create Deploy Config -weight: 2 -categories: ["Deployment", "Guides"] -tags: ["Deploy Config"] +weight: 3 description: > Create a config file to deploy your app to your Kubernetes cluster using CD-as-a-Service. --- @@ -14,11 +12,25 @@ Make sure you have [installed the CD-as-a-Service CLI]({{< ref "cli" >}}), which ## How to create a deployment config file -{{< include "create-config.md" >}} +{{< tabpane text=true right=true >}} +{{% tab header="**Platform:**" disabled=true /%}} +{{% tab header="AWS Lambda" %}} +{{< include "create-lambda-config.md" >}} +{{% /tab %}} +{{% tab header="Kubernetes" %}} +{{< include "create-k8s-config.md" >}} +{{% /tab %}} +{{< /tabpane >}} -## Deployment config file example +## Deployment config file examples -{{< include "dep-file/skeleton-config.md" >}} +### AWS Lambda + +{{< include "dep-file/lambda-skeleton-config.md" >}} + +### Kubernetes + +{{< include "dep-file/k8s-skeleton-config.md" >}} ## {{% heading "nextSteps" %}} diff --git a/content/en/deployment/kubernetes/_index.md b/content/en/deployment/kubernetes/_index.md index 5842e4e5..c9113c7c 100644 --- a/content/en/deployment/kubernetes/_index.md +++ b/content/en/deployment/kubernetes/_index.md @@ -1,9 +1,8 @@ --- -title: Kubernetes +title: Kubernetes Deployments Using Armory CD-as-a-Service linkTitle: Kubernetes -weight: 100 -no_list: false +weight: 1 exclude_search: true description: > - In this section, learn how to use Argo Rollouts with CD-as-a-Service. Also, learn how CD-as-a-Service implements Horizontal Pod Autoscaling when it's part of your deployment. + In this section, learn about Kubernetes deployments using CD-as-a-Service, how to use Argo Rollouts with CD-as-a-Service. Also, learn how CD-as-a-Service implements Horizontal Pod Autoscaling when it's part of your deployment. --- diff --git a/content/en/deployment/overview/deploy-overview.jpg b/content/en/deployment/kubernetes/overview/deploy-overview.jpg similarity index 100% rename from content/en/deployment/overview/deploy-overview.jpg rename to content/en/deployment/kubernetes/overview/deploy-overview.jpg diff --git a/content/en/deployment/overview/index.md b/content/en/deployment/kubernetes/overview/index.md similarity index 89% rename from content/en/deployment/overview/index.md rename to content/en/deployment/kubernetes/overview/index.md index 6ccad234..df665d05 100644 --- a/content/en/deployment/overview/index.md +++ b/content/en/deployment/kubernetes/overview/index.md @@ -1,11 +1,11 @@ --- -title: Deployment Overview +title: Kubernetes Deployment Overview linktitle: Overview weight: 1 description: > - Learn what an Armory CD-as-a-Service deployment is and how it works - strategies (blue/green, canary) and constraints for deploying your app to your target Kubernetes clusters. -categories: ["Canary Analysis", "Features", "Concepts"] -tags: ["Deploy Strategy", "Canary", "Blue/Green", "Kubernetes"] + Learn what an Armory CD-as-a-Service deployment to Kubernetes is and how it works - strategies (blue/green, canary) and constraints for deploying your app to your target Kubernetes clusters. +aliases: + - /deployment/overview/ --- ## What a deployment is @@ -83,17 +83,7 @@ defines how to deploy your software and route traffic. #### Target constraints -You can also configure your deployment targets to use constraints that prevent a deployment from beginning or completing until certain conditions are met. For example, you can configure your deployment to wait for your code to be deployed to your staging environment before promoting that code to production. - -You can set `beforeDeployment` or `afterDeployment` constraints depending on your use case. - -CD-as-a-Service offers you multiple constraint options including: - -* `dependsOn` - Use `dependsOn` to specify a target deployment that must successfully complete prior to starting this target's deployment. -* `pause` - Use `pause` to pause a deployment for a set period of time or until an authorized user issues an approval. - +{{< include "overview-target-constraints.md" >}} **Example** diff --git a/content/en/deployment/lambda/_index.md b/content/en/deployment/lambda/_index.md index 0e52e63f..938170dc 100644 --- a/content/en/deployment/lambda/_index.md +++ b/content/en/deployment/lambda/_index.md @@ -1,12 +1,8 @@ --- -title: Lambda -linktitle: Lambda -weight: 10 -description: > - placeholder -draft: true -no_list: false +title: AWS Lambda Deployments Using Armory CD-as-a-Service +linkTitle: AWS Lambda +weight: 1 exclude_search: true ---- - - @TODO placeholder change to DRAFT \ No newline at end of file +description: > + In this section, learn about AWS Lambda deployments using CD-as-a-Service. +--- \ No newline at end of file diff --git a/content/en/deployment/lambda/create-iam-role-lambda.md b/content/en/deployment/lambda/create-iam-role-lambda.md new file mode 100644 index 00000000..da370e45 --- /dev/null +++ b/content/en/deployment/lambda/create-iam-role-lambda.md @@ -0,0 +1,17 @@ +--- +title: Create an Armory IAM Role for AWS Lambda Deployment +linkTitle: Create Armory IAM Role +weight: 5 +description: > + Create the Armory IAM Role that CD-as-a-Service assumes when it deploys your AWS Lambda function. +--- + +## {{% heading "prereq" %}} + +Make sure you have [installed the CD-as-a-Service CLI]({{< ref "cli" >}}), which you use to load the AWS Cloud Formation template into your AWS Account. + +## Create the Armory IAM role + +{{< include "lambda/iam-role.md" >}} + +{{< include "lambda/iam-role-steps.md" >}} diff --git a/content/en/deployment/lambda/overview/index.md b/content/en/deployment/lambda/overview/index.md new file mode 100644 index 00000000..1ec56317 --- /dev/null +++ b/content/en/deployment/lambda/overview/index.md @@ -0,0 +1,295 @@ +--- +title: AWS Lambda Deployment Overview +linktitle: Overview +weight: 1 +description: > + Learn what an Armory CD-as-a-Service deployment to AWS Lambda is, how CD-as-a-Service connects to your AWS Account, and how deployment works. +--- + + +## What a deployment is + +A _deployment_ encompasses the artifacts, configuration, and actions that deliver your code to remote environments. You can configure a deployment to deliver your [AWS Lambda](https://docs.aws.amazon.com/lambda) function to a single environment or multiple environments, either in sequence or in parallel depending on your [deployment configuration]({{}}). + +You define your CD-as-a-Service deployment configuration in a YAML file, which you store within your source control, enabling code-like management. You trigger deployments using the Armory CLI, either from your CI system or your workstation. + +## How deployment works + +{{< figure src="lambda-deploy.webp" width=80%" height="80%" >}} + +CD-as-a-Service starts a deployment with a target environment, which is a combination of AWS account and region. The first target in a deployment does not depend on other targets. Then deployment progresses through the steps, conditions, and targets defined in your deployment process. + +CD-as-a-Service automatically rolls back when: + + * There is an error deploying your AWS Lambda function + * Deployment fails to finish within 30 minutes + * A webhook fails + * You configured your retrospective analysis step to automatically rollback + * A user fails to issue a configured manual approval within a specified time frame + * A deployment target constraint is not met + +How CD-as-a-Service performs rollbacks: + +* If you have specified an [AWS Lambda alias](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html) to use for routing traffic, CD-as-a-Service points the alias to the old version. +* If you have not specified an alias to use for routing traffic, CD-as-a-Service publishes a new version with the old configuration, so that the live version of your AWS Lambda function has the same configuration as before the deployment started. + +## How CD-as-a-Service integrates with AWS + +{{< include "lambda/iam-role.md" >}} + +You need to store your function zip files in an S3 bucket, and the S3 bucket should be in the same region you deploy to (this is an AWS limitation). For example, if you plan to deploy to three regions, you need three S3 buckets, one for each region. CD-as-a-Service deploys your AWS Lambda function's archive from your S3 bucket. + +| AWS Accounts | ArmoryRole | Regions | S3 Buckets | +|--------------|-----------|---------|------------| +| 1 | 1 | 4 | 4 | +| 4 | 4 | 1 | 1 | +| 4 | 4 | 4 | 4 | +| 2 | 2 | 6 | 6 | + +For each AWS Lambda function you want to deploy, CD-as-a-Service needs the following: + +1. **ArmoryRole** ARN +1. Region +1. S3 path to the function zip file +1. The ARN of your [AWS Lambda execution role](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html) +1. Your function's [runtime](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html) and handler method + +This basic example deploys one function to one region in one account: + +```yaml +version: v1 +kind: lambda +application: potatoless-facts +description: awsLambda +targets: + us-east-1: + account: armory-docs-dev + deployAsIamRole: arn:aws:iam::111111111111:role/ArmoryRole + region: us-east-1 + strategy: allAtOnce +strategies: + allAtOnce: + canary: + steps: + - setWeight: + weight: 100 +artifacts: + - functionName: potatolessFacts + path: s3://armory-docs-dev-us-east-1/potatolessfacts-justsweetpotatoes.zip + type: zipFile +providerOptions: + lambda: + - name: potatolessFacts + target: us-east-1 + runAsIamRole: arn:aws:iam::111111111111:role/lamdaExecutionRole + handler: index.handler + runtime: nodejs18.x +``` + +## How to trigger a deployment + +* [Use the CLI]({{< ref "cli" >}}) in your terminal or with any CI system by installing the CLI natively or running it in Docker. +* [Use the GitHub Action]({{< ref "integrations/ci-systems/gh-action" >}}) in your GitHub workflow. + + +## Define your deployment + +With CD-as-a-Service, you declare your deployment configuration outcome in a YAML file. + +For an AWS Lambda deployment, you only need to provide the following pieces of information: + +* The target you want to deploy to +* The AWS Lambda function you want to deploy +* Provider options for that AWS Lambda function +* The canary strategy you want to use for the deployment + +## Elements of a deployment + +### Targets + +Within a deployment, you define _targets_ that are equivalent to the environments you are deploying to - a unique combination of AWS account (ArmoryRole ARN) and region. + +The following example has multiple region-based targets in a single AWS account: + +```yaml +targets: + Prod-East-1: + account: armory-prod + deployAsIamRole: arn:aws:iam::111111111111:role/ArmoryRole + region: us-east-1 + strategy: allAtOnce + Prod-West-2: + account: armory-prod + deployAsIamRole: arn:aws:iam::111111111111:role/ArmoryRole + region: us-west-2 + strategy: allAtOnce +``` + +This example has targets that are separate AWS Accounts: + +```yaml +targets: + Lab: + account: armory-lab + deployAsIamRole: "arn:aws:iam::111111111111:role/ArmoryRole" + region: us-west-2 + strategy: rollingDeployment + Staging: + account: armory-core + deployAsIamRole: "arn:aws:iam::222222222222:role/ArmoryRole" + region: us-west-2 + strategy: rollingDeployment + Audit: + account: armory-audit + deployAsIamRole: "arn:aws:iam::333333333333:role/ArmoryRole" + region: us-west-2 + strategy: rollingDeployment + ITSec: + account: armory-itsec + deployAsIamRole: "arn:aws:iam::444444444444:role/ArmoryRole" + region: us-west-2 + strategy: rollingDeployment +``` + +#### Target constraints + +{{< include "overview-target-constraints.md" >}} + +This example has multiple targets and illustrates `dependsOn`, `beforeDeployment`, and `afterDeployment` constraints. + +```yaml +targets: + Lab: + account: armory-lab + deployAsIamRole: "arn:aws:iam::111111111111:role/ArmoryRole" + region: us-west-2 + strategy: rollingDeployment + Staging: + account: armory-core + deployAsIamRole: "arn:aws:iam::222222222222:role/ArmoryRole" + region: us-west-2 + strategy: rollingDeployment + constraints: + dependsOn: + - Lab + afterDeployment: + - runWebhook: + name: Integration-Tests + Audit: + account: armory-audit + deployAsIamRole: "arn:aws:iam::333333333333:role/ArmoryRole" + region: us-west-2 + strategy: rollingDeployment + constraints: + dependsOn: + - Lab + afterDeployment: + - runWebhook: + name: Audit-Analysis + ITSec: + account: armory-itsec + deployAsIamRole: "arn:aws:iam::444444444444:role/ArmoryRole" + region: us-west-2 + strategy: rollingDeployment + constraints: + dependsOn: + - Lab + afterDeployment: + - runWebhook: + name: Security-Scans + Prod-West-2: + account: armory-prod + deployAsIamRole: "arn:aws:iam::555555555555:role/ArmoryRole" + region: us-west-2 + strategy: rollingDeployment + constraints: + dependsOn: + - Staging + - Audit + - ITSec + beforeDeployment: + - runWebhook: + name: Send-Slack-Deployment-Approval-Required + - pause: + untilApproved: true +``` + +### Artifacts + +An _artifact_ is your AWS Lambda function name and the S3 path to the function's archive. You should have an entry for each deployment target region. The `functionName` is unique for each entry in the `artifacts` collection. + +```yaml +artifacts: + - functionName: hello-world-python + path: s3://armory-demos-us-west-2/hello-world-python.zip + type: zipFile +``` + +### Provider options + +This section is where you provide additional information about your function. Each target has an entry. + +```yaml +providerOptions: + lambda: + - target: Lab + name: hello-world-python + runAsIamRole: arn:aws:iam::111111111111:role/LambdaExecutionRole + handler: lambda_function.lambda_handler + runtime: python3.10 + - target: Staging + name: hello-world-python + runAsIamRole: arn:aws:iam::222222222222:role/LambdaExecutionRole + handler: lambda_function.lambda_handler + runtime: python3.10 + - target: Audit + name: hello-world-python + runAsIamRole: arn:aws:iam::333333333333:role/LambdaExecutionRole + handler: lambda_function.lambda_handler + runtime: python3.10 + - target: ITSec + name: hello-world-python + runAsIamRole: arn:aws:iam::444444444444:role/LambdaExecutionRole + handler: lambda_function.lambda_handler + runtime: python3.10 + - target: Prod-West-2 + name: hello-world-python + runAsIamRole: arn:aws:iam::555555555555:role/LambdaExecutionRole + handler: lambda_function.lambda_handler + runtime: python3.10 +``` + +Be sure to view the [AWS Lambda Quickstart]({{< ref "get-started/lambda" >}}) and [config file reference]({{< ref "reference/deployment/config-file/artifacts" >}}) for additional examples. + +### Strategies + +A deployment strategy is the method by which CD-as-a-Service deploys your changes to a target. Strategies can use different techniques to allow for rapid rollback should a problem be discovered, minimizing the impact of potential issues to a small subset of users. You could also use a strategy optimized for speed. + +For AWS Lambda deployments, CD-as-a-Service supports a canary deployment strategy, which involves releasing a new software version to a small subset of users or systems while leaving the majority on the current version. This strategy allows for real-world testing and monitoring of the new version's performance and stability. +If the canary users experience positive results, the new version can be gradually rolled out to a wider audience. + +This example **routes 100% of traffic** to the **new version**. You’d use this `allAtOnce` strategy to initially deploy your function to AWS Lambda when the function does not exist in the AWS Lambda console. **This strategy is also useful in non-production environments such as staging.** + +```yaml +strategies: + allAtOnce: + canary: + steps: + - setWeight: + weight: 100 +``` + +For subsequent deployments, you could use a canary strategy that splits traffic. CD-as-a-Service uses your function's AWS Lambda [alias](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html) when splitting traffic between versions. + +>You must create the alias in the AWS Lambda console before using the alias in your CD-as-a-Service deployment. + +This example is for deployment to multiple regions in a single AWS Account. The canary strategy splits traffic. You declare your function's alias in the `trafficManagement` section. There are two entries in the `trafficManagement` section since both staging and prod targets use the traffic split strategy. + +{{< readfile file="/includes/code/lambda-traffic-split-snippet.yaml" code="true" lang="yaml" >}} + + +## {{% heading "nextSteps" %}} + +* Work through the [AWS Lambda Quickstart]({{< ref "get-started/lambda" >}}) to deploy a sample function to your AWS Account. +* Learn how you can [monitor your deployment]({{< ref "deployment/monitor-deployment" >}}) using the UI or the CLI. +* View the deployment config file [reference]({{< ref "reference/deployment/config-file" >}}). diff --git a/content/en/deployment/lambda/overview/lambda-deploy.webp b/content/en/deployment/lambda/overview/lambda-deploy.webp new file mode 100644 index 00000000..be1b0835 Binary files /dev/null and b/content/en/deployment/lambda/overview/lambda-deploy.webp differ diff --git a/content/en/deployment/strategies/_index.md b/content/en/deployment/strategies/_index.md index 81fd35aa..7f419097 100644 --- a/content/en/deployment/strategies/_index.md +++ b/content/en/deployment/strategies/_index.md @@ -1,7 +1,7 @@ --- title: Canary and Blue/Green Deployment Strategies linktitle: Strategies -weight: 3 +weight: 2 no_list: false exclude_search: true description: > diff --git a/content/en/deployment/strategies/blue-green.md b/content/en/deployment/strategies/blue-green.md index 18155c61..bbc4ef30 100644 --- a/content/en/deployment/strategies/blue-green.md +++ b/content/en/deployment/strategies/blue-green.md @@ -8,6 +8,8 @@ categories: ["Deployment", "Guides"] tags: ["Deploy Strategy", "Blue/Green", "Kubernetes"] --- +**Kubernetes Only** + ## What a blue/green strategy does A blue/green strategy shifts traffic from the running version of your software (_blue_) to a new version of your software (_green_) based on conditions you set. You specify conditions that must be met prior to routing traffic to the new version and before shutting down the old version. See the [Strategies Overview]({{< ref "deployment/strategies/overview" >}}) for details on the advantages of using a blue/green deployment strategy. @@ -22,7 +24,8 @@ A blue/green strategy shifts traffic from the running version of your software ( ## {{% heading "prereq" %}} -Before configuring a blue/green strategy in your [deployment]({{< ref "deployment/overview" >}}), you should have the following: +Before configuring a blue/green strategy in your [Kubernetes deployment]({{< ref "deployment/kubernetes/overview" >}}), +you should have the following: * Kubernetes Deployment object diff --git a/content/en/deployment/strategies/canary.md b/content/en/deployment/strategies/canary.md index e856b974..86ff4e70 100644 --- a/content/en/deployment/strategies/canary.md +++ b/content/en/deployment/strategies/canary.md @@ -4,8 +4,6 @@ linkTitle: Canary weight: 5 description: > Learn how to configure a canary deployment strategy in your Armory CD-as-a-Service deployment. -categories: ["Deployment", "Guides"] -tags: ["Kubernetes", "Deploy Strategy", "Canary"] --- ## What a canary strategy does @@ -33,7 +31,8 @@ When using a canary strategy with a service mesh such as Istio or Linkerd, CD-as ## {{% heading "prereq" %}} -Before configuring a canary strategy in your [deployment]({{< ref "deployment/overview" >}}), you should have the following: +Before configuring a canary strategy in your [Kubernetes deployment]({{< ref "deployment/kubernetes/overview" >}}), you +should have the following: * Kubernetes Deployment object @@ -88,7 +87,19 @@ targets: You can define different canary strategies for different deployment targets. -## Example deployment config file +## Using canary strategies with a service mesh + +Service meshes enable setting up accurate traffic splits between the new version and the old version of your app. If you are using a service mesh, you need to add a `trafficManagement` block to your deployment config. + +```yaml +trafficManagement: + - istio: + ... +``` +For more info on using service meshes, see the [Traffic Management Overview]({{< ref "traffic-management/overview.md" >}}), which explains how CD-as-a-Service implements progressive canary deployment using an SMI TrafficSplit. + + +## Example Kubernetes deployment config file In this basic example, you deploy an app called "sample-app" to two deployment targets. @@ -180,16 +191,48 @@ spec: ``` -## Using canary strategies with a service mesh - -Service meshes enable setting up accurate traffic splits between the new version and the old version of your app. If you are using a service mesh, you need to add a `trafficManagement` block to your deployment config. +## Example AWS Lambda deployment config ```yaml -trafficManagement: - - istio: - ... +version: v1 +kind: lambda +application: Sweet Potato Lambda +description: Sweet Potato facts from a Lambda function +deploymentConfig: + timeout: + unit: minutes + duration: 10 +targets: + dev: + account: armory-docs-dev + deployAsIamRole: arn:aws:iam::111111111111:role/ArmoryRole + region: us-east-2 + strategy: trafficSplit + +strategies: + trafficSplit: + canary: + steps: + - setWeight: 10 + - pause: + untilApproved: true + - setWeight: 20 + - pause: + untilApproved: true + - setWeight: 100 +artifacts: + - functionName: just-sweet-potatoes + path: s3://armory-docs-dev-us-east-2/justsweetpotatoes.zip + type: zipFile + +providerOptions: + lambda: + - name: just-sweet-potatoes + target: dev + runAsIamRole: arn:aws:iam::111111111111:role/LamdaExecutionRole + handler: index.handler + runtime: nodejs18.x ``` -For more info on using service meshes, see the [Traffic Management Overview]({{< ref "traffic-management/overview.md" >}}), which explains how CD-as-a-Service implements progressive canary deployment using an SMI TrafficSplit. ## {{% heading "nextSteps" %}} diff --git a/content/en/deployment/strategies/overview.md b/content/en/deployment/strategies/overview.md index 4995f823..c5f9ef29 100644 --- a/content/en/deployment/strategies/overview.md +++ b/content/en/deployment/strategies/overview.md @@ -3,14 +3,15 @@ title: Deployment Strategies Overview linktitle: Overview weight: 1 description: > - Learn about blue/green and canary deployment strategies for deploying your apps to Kubernetes using Armory CD-as-a-Service. Compare features to decide which strategy fits your use case. -categories: ["Deployment Strategies", "Features", "Concepts"] -tags: ["Canary", "Blue/Green"] + Learn about blue/green and canary deployment strategies for deploying AWS Lambda functions or your apps to Kubernetes using Armory CD-as-a-Service. Compare features to decide which strategy fits your use case. --- ## {{% heading "prereq" %}} -You are familiar with [what a deployment is]({{< ref "deployment/overview" >}}) and the elements of a deployment. +You are familiar with the following deployments and the elements that comprise each type: + +* [AWS Lambda deployment]({{< ref "deployment/lambda/overview" >}}) +* [Kubernetes deployment]({{< ref "deployment/kubernetes/overview" >}}) ## What is a deployment strategy? @@ -18,6 +19,8 @@ A deployment strategy is the procedure that CD-as-a-Service uses to deploy your ## Blue/Green deployment strategy +**Kubernetes Only** + In a blue/green deployment strategy, you deploy and maintain two identical production environments throughout the execution of the deployment. You maintain _blue_ and _green_ production environments. The _blue_ environment contains the latest known stable version of your app (usually the version you are replacing with the new version) while the _green_ environment contains the changes you are currently deploying. Once you deploy to the green environment, traffic continues to flow exclusively to the blue environment, allowing you to validate and test the changes in your green environment. You can do this via manual testing, automated testing, or any other validation method you may use. diff --git a/content/en/get-started/deploy-your-app.md b/content/en/get-started/deploy-your-app.md index 832a3512..f0e63d6f 100644 --- a/content/en/get-started/deploy-your-app.md +++ b/content/en/get-started/deploy-your-app.md @@ -1,6 +1,6 @@ --- -title: Deploy Your Own App -linkTitle: Deploy Your Own App +title: Deploy Your Own App to Kubernetes +linkTitle: Deploy Your Own Kubernetes App description: > Use a canary strategy to deploy two versions of your app to your Kubernetes cluster with Armory CD-as-a-Service. Install the CLI, connect your cluster, create a deployment config file, and deploy your app to two environments. weight: 10 diff --git a/content/en/get-started/deploy-your-own-function.md b/content/en/get-started/deploy-your-own-function.md new file mode 100644 index 00000000..11120848 --- /dev/null +++ b/content/en/get-started/deploy-your-own-function.md @@ -0,0 +1,11 @@ +--- +title: Deploy Your Own Function to AWS Lambda +linkTitle: Deploy Your Own Function +description: > + tbd +weight: 10 +draft: true +--- + + - lambda function + - S3 https://docs.aws.amazon.com/lambda/latest/dg/with-s3-example.html \ No newline at end of file diff --git a/content/en/get-started/lambda/deploy-details.webp b/content/en/get-started/lambda/deploy-details.webp new file mode 100644 index 00000000..ab04676a Binary files /dev/null and b/content/en/get-started/lambda/deploy-details.webp differ diff --git a/content/en/get-started/lambda/deployed-function-list.webp b/content/en/get-started/lambda/deployed-function-list.webp new file mode 100644 index 00000000..7c0bed19 Binary files /dev/null and b/content/en/get-started/lambda/deployed-function-list.webp differ diff --git a/content/en/get-started/lambda/files/just-sweet-potatoes.zip b/content/en/get-started/lambda/files/just-sweet-potatoes.zip new file mode 100644 index 00000000..ddbf6ea3 Binary files /dev/null and b/content/en/get-started/lambda/files/just-sweet-potatoes.zip differ diff --git a/content/en/get-started/lambda/function-test.webp b/content/en/get-started/lambda/function-test.webp new file mode 100644 index 00000000..be52ccd3 Binary files /dev/null and b/content/en/get-started/lambda/function-test.webp differ diff --git a/content/en/get-started/lambda/index.md b/content/en/get-started/lambda/index.md new file mode 100644 index 00000000..26ac48bd --- /dev/null +++ b/content/en/get-started/lambda/index.md @@ -0,0 +1,361 @@ +--- +title: Quickstart AWS Lambda Deployment +linktitle: Quickstart AWS Lambda +description: > + Quickly get started using Armory CD-as-a-Service to deploy a function to AWS Lambda. Install the CLI, connect to AWS Lambda with a single command, and deploy a sample function. Learn deployment file syntax. +weight: 2 +--- + + +## {{% heading "prereq" %}} + +* You have read the {{< linkWithTitle "deployment/lambda/overview/index.md" >}}. +* AWS requirements: + * You need an [AWS Account](https://aws.amazon.com/free/), and you must have authority to create an IAM Role. + * You should be familiar with [AWS Lambda](https://aws.amazon.com/lambda/). + * You need an [AWS Lambda execution role](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html). + +## Learning objectives + +In this guide, you deploy an AWS Lambda function to four regions in your AWS Lambda account. + +1. [Sign up for CD-as-a-Service](#sign-up-for-cd-as-a-service). +1. [Install the CD-as-as-Service CLI](#install-the-cd-as-as-service-cli) on your Mac, Linux, or Windows workstation. +1. Create AWS artifacts + 1. [Create the IAM Role](#create-the-armory-iam-role) that CD-as-a-Service assumes to deploy your function. + 1. [Create S3 buckets](#create-s3-buckets), one for each deployment region, to house your function's zip files. + 1. [Upload the sample function](#upload-the-aws-lambda-function-to-your-buckets) to each S3 bucket. +1. [Create your CD-as-a-Service deployment config file](#create-your-deployment-config-file). +1. [Deploy the sample function](#deploy-the-sample-function). +1. [Test the deployed function](#test-the-deployed-function) in the AWS Lambda console. + +## Sign up for CD-as-a-Service + +{{< include "register.md" >}} + +## Install the CD-as-as-Service CLI + +{{< include "cli/install-cli-tabpane.md" >}} + +### Log in with the CLI + +```shell +armory login +``` + +Confirm the device code in your browser when prompted. Then return to this guide. + +## Create the Armory IAM role + +{{< include "lambda/iam-role.md" >}} + +{{< include "lambda/iam-role-steps.md" >}} + +## Create S3 buckets + +You need to store your AWS Lambda function as a zip file in an S3 bucket, and S3 bucket needs to be in the same region you deploy to. For this guide, you are going to deploy the AWS Lambda function to four regions so you need to create four buckets: + + +| Region | Bucket Name | +| ---------|----------| +| us-east-1 | armory-demo-east-1 | +| us-east-2 | armory-demo-east-2 | +| us-west-1 | armory-demo-west-1 | +| us-west-2 | armory-demo-west-2 | + +Use the default values for the rest of the fields. + +After you have finished, you should have four buckets. + +{{< figure src="s3-buckets.webp" >}} + +## Upload the AWS Lambda function to your buckets + +Armory provides a basic AWS Lambda function called `just-sweet-potatoes` for you to deploy. + +
Expand to see the code + +`index.js` has the following content: + +```js +exports.handler = async (event) => { + + const randomFact = potatolessFacts[Math.floor(Math.random() * potatolessFacts.length)]; + + // Prepare the response + const response = { + statusCode: 200, + body: randomFact, + }; + + return response; +}; + +const potatolessFacts = [ + "Sweet potatoes are a great source of vitamin A, which is important for vision health.", + "There are over 400 varieties of sweet potatoes around the world.", + "Sweet potatoes are not related to regular potatoes; they belong to the morning glory family.", + "Sweet potatoes are high in fiber, making them good for digestion.", + "Sweet potatoes come in different colors, including orange, purple, and white.", + "Sweet potatoes are one of the oldest vegetables known to man.", + "North Carolina is the largest producer of sweet potatoes in the United States.", + "Sweet potatoes are often used in Thanksgiving dishes like casseroles and pies.", + ]; +``` + +
+ +1. Download the function zip file. +1. Upload the file to each of your `armory-demo-lambda-deploy` S3 buckets. +1. Make a note of each bucket's S3 path to the lambda function. The paths should be: + + * `s3://armory-demo-east-1/just-sweet-potatoes.zip` + * `s3://armory-demo-east-2/just-sweet-potatoes.zip` + * `s3://armory-demo-west-1/just-sweet-potatoes.zip` + * `s3://armory-demo-west-2/just-sweet-potatoes.zip` + +## Create your deployment config file + +First create a file called `deploy.yaml` with the following contents: + +{{< highlight yaml "linenos=table" >}} +version: v1 +kind: lambda +application: just-sweet-potatoes +description: A sample function for deployment using CD-as-a-Service +{{< /highlight >}} + +* `kind`: `lambda` tells CD-as-a-Service the deployment type +* `application`: This is the unique name of your deployment and appears in the **Deployments** list. +* `description`: Brief description of your function (optional) + +### Add a canary strategy + +A strategy defines how CD-as-a-Service deploys your AWS Lambda function to a target. + +A [canary strategy]({{< ref "deployment/strategies/canary.md" >}}) is a linear sequence of steps. The `setWeight` step defines the ratio of traffic between function versions. + + +Add a basic [canary strategy]({{< ref "deployment/strategies/canary" >}}) with a single step that sets the weight to 100. This routes 100% of traffic to the new version. You use this `allAtOnce` strategy to initially deploy your function to AWS Lambda when the function does not exist in the AWS Lambda console. This strategy is also useful in non-production environments such as staging. + +{{< highlight yaml "linenos=table" >}} +strategies: + allAtOnce: + canary: + steps: + - setWeight: + weight: 100 +{{< /highlight >}} + +### Add targets + +In CD-as-a-Service, a `target` is an (AWS Account, region) pair. + +```mermaid +flowchart LR + A[dev] --> B[staging] + B --> C[prod-west-1] + B --> D[prod-west-2] +``` + +When deploying to multiple targets, you can specify dependencies between targets using the `constraints.dependsOn` field. CD-as-a-Service deploys your AWS Lambda function from your S3 bucket to the `dev` target first. You want a linear, success-dependent progression from `dev` to `prod`, so there is a `dependsOn` constraint for staging and prod targets. `staging` depends on `dev` and the prod targets depend on `staging`. + +Add the four targets, one in each region: + +{{< highlight yaml "linenos=table" >}} +targets: + dev: + account: + deployAsIamRole: + region: us-east-1 + strategy: allAtOnce + staging: + account: + deployAsIamRole: + region: us-east-2 + strategy: allAtOnce + constraints: + dependsOn: + - dev + prod-west-1: + account: + deployAsIamRole: + region: us-west-1 + strategy: allAtOnce + constraints: + dependsOn: + - staging + prod-west-2: + account: + deployAsIamRole: + region: us-west-2 + strategy: allAtOnce + constraints: + dependsOn: + - staging +{{< /highlight >}} + +Replace: + +* `` with the name of your AWS Account, such as `armory-docs-dev` +* `` with the ARN of the role you created in the [Create the Armory IAM role](#create-the-armory-iam-role) section + + +### Add AWS Lambda artifacts + +In this section, you declare your AWS Lambda function artifacts. You have an entry for each deployment region. + +The function is named `just-sweet-potatoes` in each S3 bucket, but the `functionName` is unique for each entry in the +`artifacts` collection. For this guide, the target name is appended to the function's name to create the +`functionName` value for each entry. + +{{< highlight yaml "linenos=table" >}} +artifacts: + - functionName: just-sweet-potatoes-dev + path: s3://armory-demo-east-1/just-sweet-potatoes.zip + type: zipFile + - functionName: just-sweet-potatoes-staging + path: s3://armory-demo-east-2/just-sweet-potatoes.zip + type: zipFile + - functionName: just-sweet-potatoes-prod-west-1 + path: s3://armory-demo-west-1/just-sweet-potatoes.zip + type: zipFile + - functionName: just-sweet-potatoes-prod-west-2 + path: s3://armory-demo-west-2/just-sweet-potatoes.zip + type: zipFile +{{< /highlight >}} + +### Add provider options + +This section defines options specific to the cloud provider to which you are deploying. You need to populate provider options for each deployment target. + +{{< highlight yaml "linenos=table" >}} +providerOptions: + lambda: + - target: dev + name: just-sweet-potatoes-dev + runAsIamRole: + handler: index.handler + runtime: python3.10 + - target: staging + name: just-sweet-potatoes-staging + runAsIamRole: + handler: index.handler + runtime: python3.10 + - target: prod-west-1 + name: just-sweet-potatoes-prod-west-1 + runAsIamRole: + handler: index.handler + runtime: python3.10 + - target: prod-west-2 + name: just-sweet-potatoes-prod-west-2 + runAsIamRole: + handler: index.handler + runtime: python3.10 +{{< /highlight >}} + +{{< include "dep-file/lambda-provider-options.md" >}} + +## Deploy the sample function + +### First deployment + +Start your deployment using the CLI: + +```bash +armory deploy start -f deploy.yaml +``` + +You can use the link provided by the CLI to observe your deployment's progression in the [CD-as-a-Service Console](https://console.cloud.armory.io/deployments). CD-as-a-Service deploys your resources to `dev`. Once those resources have deployed successfully, CD-as-a-Service deploys to `staging` and then `prod`. + +{{< figure src="deploy-details.webp" width="80%" height="80%" >}} + +### Second deployment + +CD-as-a-Service is designed to help you build safety into your app deployment process. It does so by giving you declarative levers to control the scope of your deployment. + +CD-as-a-Service has four kinds of constraints that you can use to control your deployment: + +- Manual Approvals +- Timed Pauses +- [External Automation (Webhooks)]({{< ref "webhooks/overview.md" >}}) to run integration tests and security audits or send notifications +- [Automated Canary Analysis]({{< ref "deployment/strategies/canary" >}}) + +You can use these constraints between environments and within environments. During your next deployment, you want to issue a manual approval before deploying to to the prod targets. Add to your `staging` target an `afterDeployment` constraint with a manual judgment: + +{{< highlight yaml "linenos=table,hl_lines=15-17" >}} +targets: + dev: + account: + deployAsIamRole: + region: us-east-1 + strategy: allAtOnce + staging: + account: + deployAsIamRole: + region: us-east-2 + strategy: allAtOnce + constraints: + dependsOn: + - dev + afterDeployment: + - pause: + untilApproved: true + prod-west-1: + account: + deployAsIamRole: + region: us-west-1 + strategy: allAtOnce + constraints: + dependsOn: + - staging + prod-west-2: + account: + deployAsIamRole: + region: us-west-2 + strategy: allAtOnce + constraints: + dependsOn: + - staging +{{< /highlight>}} + + +Start your second deployment using the CLI: + +```bash +armory deploy start -f deploy.yaml +``` + +Use the link provided by the CLI to observe your deployment's progression in the [CD-as-a-Service Console](https://console.cloud.armory.io/deployments). + +In this second deployment, you see that CD-as-a-Service paused deployment to prod. Click the **Approve** button in the `staging` node to continue deployment. + +{{< figure src="manual-constraint.webp" width="80%" height="80%" >}} + +## Test the deployed function + +Go to the `us-east-1` Lamba section of your AWS Account. You should see your deployed `just-sweet-potatoes-dev` function there. + +{{< figure src="deployed-function-list.webp" width="80%" height="80%" >}} + + +1. Click `just-sweet-potatoes-dev` to open the function's details page. +1. Click the **Test** tab. +1. Click the **Test** button in the **Test event** section to test the function. +1. Expand the **Details** section to see the test results. + + {{< figure src="function-test.webp" >}} + + +## Clean up + +1. Delete the deployed AWS Lambda functions from each region. +1. Delete the AWS Lambda zip files from each S3 bucket. Delete each S3 bucket. +1. Delete the CloudFormation Stack. This also deletes the associated IAM Role. + + +## {{% heading "nextSteps" %}} + +* {{< linkWithTitle "integrations/ci-systems/gh-action.md" >}} +* {{< linkWithTitle "deployment/strategies/canary.md" >}} +* {{< linkWithTitle "webhooks/overview.md" >}} \ No newline at end of file diff --git a/content/en/get-started/lambda/manual-constraint.webp b/content/en/get-started/lambda/manual-constraint.webp new file mode 100644 index 00000000..4374e02f Binary files /dev/null and b/content/en/get-started/lambda/manual-constraint.webp differ diff --git a/content/en/get-started/lambda/s3-buckets.webp b/content/en/get-started/lambda/s3-buckets.webp new file mode 100644 index 00000000..291fdbe1 Binary files /dev/null and b/content/en/get-started/lambda/s3-buckets.webp differ diff --git a/content/en/get-started/overview.md b/content/en/get-started/overview.md index 35038562..dc2128c2 100644 --- a/content/en/get-started/overview.md +++ b/content/en/get-started/overview.md @@ -2,22 +2,31 @@ title: How to Get Started using Armory CD-as-a-Service linkTitle: Overview description: > - Learn what you need to get started deploying an app to Kubernetes using Armory Continuous Deployment-as-a-Service. + Learn what you need to get started deploying your AWS Lambda function or an app to Kubernetes. weight: 1 -categories: ["Get Started", "Concepts"] -tags: ["Quickstart", "Deployment"] --- ## What you need to use CD-as-a-Service -You need a Mac, Linux, or Windows workstation and access to a Kubernetes cluster. If you need a cluster, consider installing a local [Kind](https://kind.sigs.k8s.io/docs/user/quick-start/) or [Minikube](https://minikube.sigs.k8s.io/docs/start/) cluster. Your cluster's API endpoint does not need to be publicly accessible to use CD-as-a-Service. +You need a Mac, Linux, or Windows workstation and access to a Kubernetes cluster or AWS Lambda. -## Deploy a sample app provided by Armory +If you need a Kubernetes cluster, consider installing a local [Kind](https://kind.sigs.k8s.io/docs/user/quick-start/) or [Minikube](https://minikube.sigs.k8s.io/docs/start/) cluster. Your cluster's API endpoint does not need to be publicly accessible to use CD-as-a-Service. Alternately, you can use a interactive learning environment like [Killercoda](https://killercoda.com/learn). + + +## AWS Lambda + +### Deploy a sample app provided by Armory + + * Written [Quickstart guide]({{< ref "get-started/lambda.md" >}}) deploying a sample function to your AWS account + +## Kubernetes + +### Deploy a sample app provided by Armory * [Guided UI tour](https://console.cloud.armory.io/getting-started) using an Armory sandbox cluster * Written [Quickstart guide]({{< ref "get-started/quickstart.md" >}}) deploying a sample app to your own cluster -## Deploy your own app to your cluster +### Deploy your own app to your cluster * [Guided UI tour](https://console.cloud.armory.io/getting-started?gettingStartedPane=InstallFlowPane) * Written [Deploy Your Own App]({{< ref "get-started/deploy-your-app.md" >}}) guide \ No newline at end of file diff --git a/content/en/get-started/quickstart/index.md b/content/en/get-started/quickstart/index.md index 80cdb2c2..c00fd912 100644 --- a/content/en/get-started/quickstart/index.md +++ b/content/en/get-started/quickstart/index.md @@ -1,8 +1,8 @@ --- -title: Quickstart -linktitle: Quickstart +title: Quickstart Kubernetes Deployment +linktitle: Quickstart Kubernetes description: > - Quickly get started using Armory CD-as-a-Service. Install the CLI, connect your Kubernetes cluster with a single command, and deploy a sample app using a canary traffic split strategy. Learn deployment file syntax. + Quickly get started using Armory CD-as-a-Service to deploy a sample app to Kubernetes. Install the CLI, connect your Kubernetes cluster with a single command, and deploy a sample app using a canary traffic split strategy. Learn deployment file syntax. weight: 2 categories: ["Get Started", "Guides"] tags: ["Deployment", "Quickstart"] diff --git a/content/en/includes/dep-file/deploy-example.yaml b/content/en/includes/code/k8s-skeleton.yaml similarity index 100% rename from content/en/includes/dep-file/deploy-example.yaml rename to content/en/includes/code/k8s-skeleton.yaml diff --git a/content/en/includes/code/lambda-skeleton.yaml b/content/en/includes/code/lambda-skeleton.yaml new file mode 100644 index 00000000..2f7a9a28 --- /dev/null +++ b/content/en/includes/code/lambda-skeleton.yaml @@ -0,0 +1,73 @@ +--- +version: v1 +kind: lambda +application: +targets: + : + account: + region: + deployAsIamRole: + strategy: + constraints: + dependsOn: + - + - +artifacts: + - functionName: + path: # S3 bucket + type: zipFile +providerOptions: + lambda: + - handler: # typically index.handler + name: + runAsIamRole: + runtime: # nodejs18.x, Python, etc + target: +strategies: + : + canary: + steps: + - pause: + duration: + unit: + - setWeight: + weight: 100 + - runWebhook: + name: +trafficManagement: + - targets: [""] + alias: + - functionName: + aliasName: +analysis: + defaultMetricProviderName: + queries: + - name: + upperLimit: + lowerLimit: + queryTemplate: >- + +webhooks: + - name: + method: + uriTemplate: + networkMode: + agentIdentifier: + headers: + - key: Authorization + value: + - key: Content-Type + value: application/json + bodyTemplate: + inline: >- + { + "event_type": "", + "client_payload": { + "callbackUri": "{{armory.callbackUri}}/callback" + } + } + retryCount: +deploymentConfig: + timeout: + unit: + duration: diff --git a/content/en/includes/code/lambda-traffic-split-snippet.yaml b/content/en/includes/code/lambda-traffic-split-snippet.yaml new file mode 100644 index 00000000..e8b18d51 --- /dev/null +++ b/content/en/includes/code/lambda-traffic-split-snippet.yaml @@ -0,0 +1,49 @@ +targets: + prod-us-east-1: + account: armory-docs-dev + region: us-east-1 + deployAsIamRole: "arn:aws:iam::111111111111:role/ArmoryRole" + strategy: trafficSplit + prod-us-east-2: + account: armory-docs-dev + region: us-east-2 + deployAsIamRole: "arn:aws:iam::111111111111:role/ArmoryRole" + strategy: trafficSplit +strategies: + trafficSplit: + canary: + steps: + - setWeight: + weight: 25 + - pause: + untilApproved: true + - setWeight: + weight: 100 +artifacts: + - functionName: just-sweet-potatoes-us-east-1 + path: s3://armory-demo-east-1/just-sweet-potatoes.zip + type: zipFile + - functionName: just-sweet-potatoes-us-east-2 + path: s3://armory-demo-east-2/just-sweet-potatoes.zip + type: zipFile +providerOptions: + lambda: + - name: just-sweet-potatoes-us-east-1 + target: prod-us-east-1 + runAsIamRole: "arn:aws:iam::111111111111:role/LambdaExecutionRole" + handler: index.handler + runtime: nodejs18.x + - name: just-sweet-potatoes-us-east-2 + target: prod-us-east-2 + runAsIamRole: "arn:aws:iam::111111111111:role/LambdaExecutionRole" + handler: index.handler + runtime: nodejs18.x +trafficManagement: + - targets: ['prod-us-east-1'] + alias: + - functionName: just-sweet-potatoes-us-east-1 + aliasName: live-version + - targets: ['prod-us-east-2'] + alias: + - functionName: just-sweet-potatoes-us-east-2 + aliasName: live-version diff --git a/content/en/includes/create-config.md b/content/en/includes/create-k8s-config.md similarity index 100% rename from content/en/includes/create-config.md rename to content/en/includes/create-k8s-config.md diff --git a/content/en/includes/create-lambda-config.md b/content/en/includes/create-lambda-config.md new file mode 100644 index 00000000..a322c93a --- /dev/null +++ b/content/en/includes/create-lambda-config.md @@ -0,0 +1,56 @@ +1. Create a YAML file with this basic content: + + ```yaml + version: v1 + kind: lambda + application: + strategies: + canary: + steps: + - setWeight: + weight: 100 + targets: + : + account: + deployAsIamRole: + region: + strategy: canary + artifacts: + - functionName: + path: + type: zipFile + providerOptions: + lambda: + - target: + name: + runAsIamRole: + handler: + runtime: + ``` + + These sections are the minimum you need to declare to deploy an AWS Lambda function. + +1. Customize your deployment file by setting the following minimum set of parameters: + + - `application`: The name of your function. This appears in the **Deployments** list page. + - `targets.`: A descriptive name for your deployment. + + * `account`: A descriptive name for the AWS Account this target resides in, such as `armory-docs-dev`. + * `deployAsIamRole`: The ARN of the [ArmoryRole]({{< ref "deployment/lambda/create-iam-role-lambda" >}}) that + CD-as-a-Service assumes to deploy your function. + * `region`: The AWS Region to deploy your function to. + + * `artifacts` + + * `functionName`: A unique name for each entry in the `artifacts` collection. + * `path`: The S3 path to your function's zip file. + + * `providerOptions.lambda` + + {{< include "dep-file/lambda-provider-options.md" >}} + +1. (Optional) Ensure there are no YAML issues with your deployment file. + + Since a hidden tab in your YAML can cause your deployment to fail, it's a good idea to validate the structure and syntax in your deployment file. There are several online linters, IDE-based linters, and command line linters such as `yamllint` that you can use to validate your deployment file. + +> You can view detailed configuration options in the {{< linkWithTitle "reference/deployment/config-file/_index.md" >}} section. diff --git a/content/en/includes/dep-file/skeleton-config.md b/content/en/includes/dep-file/k8s-skeleton-config.md similarity index 71% rename from content/en/includes/dep-file/skeleton-config.md rename to content/en/includes/dep-file/k8s-skeleton-config.md index d719a29d..9c06338a 100644 --- a/content/en/includes/dep-file/skeleton-config.md +++ b/content/en/includes/dep-file/k8s-skeleton-config.md @@ -2,5 +2,5 @@ Expand to see a skeleton config file for a deployment to Kubernetes. All all con
Click to view a skeleton deployment config file
-{{< readfile file="/includes/dep-file/deploy-example.yaml" code="true" lang="yaml" >}} +{{< readfile file="/includes/code/k8s-skeleton.yaml" code="true" lang="yaml" >}}
\ No newline at end of file diff --git a/content/en/includes/dep-file/lambda-provider-options.md b/content/en/includes/dep-file/lambda-provider-options.md new file mode 100644 index 00000000..d967f338 --- /dev/null +++ b/content/en/includes/dep-file/lambda-provider-options.md @@ -0,0 +1,5 @@ +* `target`: CD-as-a-Service deployment [target]({{< ref "reference/deployment/config-file/targets" >}}) name +* `name`: This is the same value as `artifacts.functionName` and `trafficManagement.alias.functionName` for the target region. This function name appears on your AWS Lambda **Functions** list page. +* `runAsIamRole`: Replace `` with the ARN of your [AWS Lambda execution role](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html), which is **not** the ArmoryRole ARN. +* `handler`: The function's handler method, such as `index.handler`. This value is written to the **Runtime settings** section in the AWS Lambda function details page. +* `runtime`: [runtime identifier](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html), such as `python3.22` or `nodejs18.x`. This value is written to the **Runtime settings** section in the AWS Lambda function details page. diff --git a/content/en/includes/dep-file/lambda-skeleton-config.md b/content/en/includes/dep-file/lambda-skeleton-config.md new file mode 100644 index 00000000..67761065 --- /dev/null +++ b/content/en/includes/dep-file/lambda-skeleton-config.md @@ -0,0 +1,6 @@ +Expand to see a skeleton config file for a deployment to AWS Lambda. All all config options are listed for each section. + +
Click to view a skeleton deployment config file +
+{{< readfile file="/includes/code/lambda-skeleton.yaml" code="true" lang="yaml" >}} +
\ No newline at end of file diff --git a/content/en/includes/lambda/iam-role-steps.md b/content/en/includes/lambda/iam-role-steps.md new file mode 100644 index 00000000..bb3e6c23 --- /dev/null +++ b/content/en/includes/lambda/iam-role-steps.md @@ -0,0 +1,12 @@ +1. In your default browser, log in to your AWS Account. You must have permissions to configure IAM roles. +1. In your terminal, execute the following: + + ```bash + armory aws create-role + ``` + + Type `Y` in the terminal to continue with Stack creation. This opens your browser to the CloudFormation page of your AWS Console. You complete the rest of this process in your browser. + +1. Review the resources that CD-as-a-Service is creating in your AWS account. The default IAM Role name is **ArmoryRole**. +1. Click **Create** on the AWS CloudFormation page and wait for Stack creation to finish. +1. After the CloudFormation Stack creation finishes, locate the created role ARN in the **Outputs** section. You can find it under the key **RoleArnOutput**. Make note of the ARN since you use it in your deployment config file. \ No newline at end of file diff --git a/content/en/includes/lambda/iam-role.md b/content/en/includes/lambda/iam-role.md new file mode 100644 index 00000000..8189db1e --- /dev/null +++ b/content/en/includes/lambda/iam-role.md @@ -0,0 +1 @@ +In order to deploy AWS resources, CD-as-a-Service needs to create a Trust Relationship in your AWS account by adding an IAM role. CD-as-a-Service assumes this role to execute deployments on your behalf. The Armory CLI provides a function that creates an [AWS CloudFormation Stack](https://docs.aws.amazon.com/cloudformation/) with an IAM Role, by default named **ArmoryRole**. You need to create a Stack in each AWS Account you want to deploy your AWS Lambda functions to. \ No newline at end of file diff --git a/content/en/includes/overview-target-constraints.md b/content/en/includes/overview-target-constraints.md new file mode 100644 index 00000000..41346601 --- /dev/null +++ b/content/en/includes/overview-target-constraints.md @@ -0,0 +1,7 @@ +You can also configure your deployment targets to use constraints that prevent a deployment from beginning or completing until certain conditions are met. For example, you can configure your deployment to wait for your code to be deployed to your staging environment before promoting that code to production. + +CD-as-a-Service offers you multiple constraint options including: + +* `dependsOn`: Use `dependsOn` to specify a target deployment that must successfully complete prior to starting this target's deployment. +* `beforeDeployment`: You can use this constraint to implement a checklist of things that need to happen before a target starts deploying. For example, you can use the `beforeDeployment` constraints with the [pause step]({{< ref "reference/deployment/config-file/targets#pause" >}}) to require a manual approval. +* `afterDeployment`: You can use this constraint to prevent downstream deployments from starting until some set of post deployment tasks finishes. For example, you can use this with the [runWebhook step]({{< ref "reference/deployment/config-file/targets#run-a-webhook" >}}) to execute a set of end-to-end tests in a staging environment before deploying to production. diff --git a/content/en/integrations/ci-systems/gh-action.md b/content/en/integrations/ci-systems/gh-action.md index cb78e96e..e861c401 100644 --- a/content/en/integrations/ci-systems/gh-action.md +++ b/content/en/integrations/ci-systems/gh-action.md @@ -58,7 +58,7 @@ Then the value you use for `manifests.path` in your `deployment.yaml` would be ` ### Create a deployment file -{{< include "create-config.md" >}} +{{< include "create-k8s-config.md" >}} Save your deployment file to a directory in your repo. You use this path later when you configure the GitHub Action's `path-to-file` parameter. diff --git a/content/en/reference/deployment/_index.md b/content/en/reference/deployment/_index.md index 5dd3cec3..b4f6961c 100644 --- a/content/en/reference/deployment/_index.md +++ b/content/en/reference/deployment/_index.md @@ -17,7 +17,7 @@ Make sure you have [installed the CD-as-a-Service CLI]({{< ref "cli" >}}), which ## Templates -You can generate a template file by running the following command with the CLI: +You can generate a Kubernetes deployment config file template by running the following command with the CLI: Basic template: @@ -48,13 +48,27 @@ armory template kubernetes [template-type] > deployment-template.yaml ## How to create a deployment config file -{{< include "create-config.md" >}} +{{< tabpane text=true right=true >}} +{{% tab header="**Platform:**" disabled=true /%}} +{{% tab header="AWS Lambda" %}} +{{< include "create-lambda-config.md" >}} +{{% /tab %}} +{{% tab header="Kubernetes" %}} +{{< include "create-k8s-config.md" >}} +{{% /tab %}} +{{< /tabpane >}} -## Deployment config file example -{{< include "dep-file/skeleton-config.md" >}} +## Deployment config file examples +### AWS Lambda + +{{< include "dep-file/lambda-skeleton-config.md" >}} + +### Kubernetes + +{{< include "dep-file/k8s-skeleton-config.md" >}} ## {{% heading "nextSteps" %}} diff --git a/content/en/reference/deployment/config-file/_index.md b/content/en/reference/deployment/config-file/_index.md index 1ede758e..800ea933 100644 --- a/content/en/reference/deployment/config-file/_index.md +++ b/content/en/reference/deployment/config-file/_index.md @@ -3,20 +3,15 @@ title: Deployment Config File Reference linkTitle: Deployment Config File weight: 1 description: > - The deployment config file is where you configure your app for deployment by Armory CD-as-a-Service. This config file includes application, deploymentConfig, targets, manifests, strategies, analysis, webhooks, and trafficManagement definitions. -categories: ["Reference"] -tags: ["Deployment", "Deploy Config"] + The deployment config file is where you configure your AWS Lambda function or Kubernetes app for deployment by Armory CD-as-a-Service. This config file includes application, artifacts, provider options, deploymentConfig, targets, manifests, strategies, analysis, webhooks, and trafficManagement definitions. --- -## Deployment config file example - -{{< include "dep-file/skeleton-config.md" >}} - - - - - +## Deployment config file examples +### AWS Lambda +{{< include "dep-file/lambda-skeleton-config.md" >}} +### Kubernetes +{{< include "dep-file/k8s-skeleton-config.md" >}} diff --git a/content/en/reference/deployment/config-file/application.md b/content/en/reference/deployment/config-file/application.md index dfa6dade..38ec78fe 100644 --- a/content/en/reference/deployment/config-file/application.md +++ b/content/en/reference/deployment/config-file/application.md @@ -1,15 +1,17 @@ --- -title: Application Config +title: Application and Kind Config description: > - Define your app name. + Declare your app name and specify whether the deployment is to Kubernetes or AWS Lambda. --- -## Application + +## Fields ```yaml version: v1 -kind: kubernetes -application: +kind: +application: ``` -Provide a descriptive name for your application so that you can identify it when viewing the status of your deployment in the **Deployments UI** and other locations. +- `kind`: `kubernetes` or `lambda` +- `application`: Provide a descriptive name for your Kubernetes app or Lambda function so that you can identify it when viewing the status of your deployment in the **Deployments UI** and other locations. diff --git a/content/en/reference/deployment/config-file/artifacts.md b/content/en/reference/deployment/config-file/artifacts.md new file mode 100644 index 00000000..6d448854 --- /dev/null +++ b/content/en/reference/deployment/config-file/artifacts.md @@ -0,0 +1,250 @@ +--- +title: Artifacts and Provider Options (AWS Lambda) +description: > + Declare your AWS Lambda artifacts (functionName, path, type) and provider options. +--- + +**AWS Lambda Only** + +## Artifacts + +This section defines the AWS Lambda artifacts you are deploying. The artifacts reach all target for which there is a provider option block for that function name. + +```yaml +artifacts: + - functionName: + path: + type: zipFile +``` + +* `functionName`: A unique name for each entry in the `artifacts` collection. You also use this value for `providerOptions.lambda.name` and `trafficManagement.alias.functionName`. +* `path`: The S3 path to your function's zip file +* `type`: This value is always `zipFile`. CD-as-a-Service does not support deploying AWS Lambda containers. + +>If you want to deploy to multiple regions in the same AWS Account, your `functionName` should be unique for each region. + +In this example, you deploy a function called `just-sweet-potatoes` to four regions in the same AWS Account: + +```yaml +targets: + dev: + account: + deployAsIamRole: + region: us-east-1 + strategy: allAtOnce + staging: + account: + deployAsIamRole: + region: us-east-2 + strategy: allAtOnce + constraints: + dependsOn: + - dev + prod-west-1: + account: + deployAsIamRole: + region: us-west-1 + strategy: allAtOnce + constraints: + dependsOn: + - staging + prod-west-2: + account: + deployAsIamRole: + region: us-west-2 + strategy: allAtOnce + constraints: + dependsOn: + - staging +artifacts: + - functionName: just-sweet-potatoes-us-east-1 + path: s3://armory-demo-east-1/just-sweet-potatoes.zip + type: zipFile + - functionName: just-sweet-potatoes-us-east-2 + path: s3://armory-demo-east-2/just-sweet-potatoes.zip + type: zipFile + - functionName: just-sweet-potatoes-prod-west-1 + path: s3://armory-demo-west-1/just-sweet-potatoes.zip + type: zipFile + - functionName: just-sweet-potatoes-prod-west-2 + path: s3://armory-demo-west-2/just-sweet-potatoes.zip + type: zipFile +``` + +## Provider options + +This section defines options specific to the cloud provider to which you are deploying. You need to populate provider options for each deployment target. + +```yaml +providerOptions: + lambda: + - name: + target: + runAsIamRole: + handler: + runtime: +``` + +{{< include "dep-file/lambda-provider-options.md" >}} + +```yaml +targets: + dev: + account: + deployAsIamRole: + region: us-east-1 + strategy: allAtOnce + staging: + account: + deployAsIamRole: + region: us-east-2 + strategy: allAtOnce + constraints: + dependsOn: + - dev + prod-west-1: + account: + deployAsIamRole: + region: us-west-1 + strategy: allAtOnce + constraints: + dependsOn: + - staging + prod-west-2: + account: + deployAsIamRole: + region: us-west-2 + strategy: allAtOnce + constraints: + dependsOn: + - staging +artifacts: + - functionName: just-sweet-potatoes-us-east-1 + path: s3://armory-demo-east-1/just-sweet-potatoes.zip + type: zipFile + - functionName: just-sweet-potatoes-us-east-2 + path: s3://armory-demo-east-2/just-sweet-potatoes.zip + type: zipFile + - functionName: just-sweet-potatoes-prod-west-1 + path: s3://armory-demo-west-1/just-sweet-potatoes.zip + type: zipFile + - functionName: just-sweet-potatoes-prod-west-2 + path: s3://armory-demo-west-2/just-sweet-potatoes.zip + type: zipFile +providerOptions: + lambda: + - name: just-sweet-potatoes-us-east-1 + target: dev + runAsIamRole: + handler: index.handler + runtime: python3.10 + - name: just-sweet-potatoes-us-east-2 + target: staging + runAsIamRole: + handler: index.handler + runtime: python3.10 + - name: just-sweet-potatoes-prod-west-1 + target: prod-west-1 + runAsIamRole: + handler: index.handler + runtime: python3.10 + - name: just-sweet-potatoes-prod-west-2 + target: prod-west-2 + runAsIamRole: + handler: index.handler + runtime: python3.10 +``` + +## Multiple AWS Accounts example + +This illustrates deploying a function to the same region in multiple AWS Accounts. + +```yaml +targets: + Lab: + account: armory-lab + deployAsIamRole: "arn:aws:iam::111111111111:role/ArmoryRole" + region: us-west-2 + strategy: rollingDeployment + Staging: + account: armory-core + deployAsIamRole: "arn:aws:iam::222222222222:role/ArmoryRole" + region: us-west-2 + strategy: rollingDeployment + constraints: + dependsOn: + - Lab + afterDeployment: + - runWebhook: + name: Integration-Tests + Audit: + account: armory-audit + deployAsIamRole: "arn:aws:iam::333333333333:role/ArmoryRole" + region: us-west-2 + strategy: rollingDeployment + constraints: + dependsOn: + - Lab + afterDeployment: + - runWebhook: + name: Audit-Analysis + ITSec: + account: armory-itsec + deployAsIamRole: "arn:aws:iam::444444444444:role/ArmoryRole" + region: us-west-2 + strategy: rollingDeployment + constraints: + dependsOn: + - Lab + afterDeployment: + - runWebhook: + name: Security-Scans + Prod-West-2: + account: armory-prod + deployAsIamRole: "arn:aws:iam::555555555555:role/ArmoryRole" + region: us-west-2 + strategy: rollingDeployment + constraints: + dependsOn: + - Staging + - Audit + - ITSec + beforeDeployment: + - runWebhook: + name: Send-Slack-Deployment-Approval-Required + - pause: + untilApproved: true +artifacts: + - functionName: hello-world-python + path: s3://armory-demos-us-west-2/hello-world-python.zip + type: zipFile +providerOptions: + lambda: + - target: Lab + name: hello-world-python + runAsIamRole: arn:aws:iam::111111111111:role/LambdaExecutionRole + handler: lambda_function.lambda_handler + runtime: python3.10 + - target: Staging + name: hello-world-python + runAsIamRole: arn:aws:iam::222222222222:role/LambdaExecutionRole + handler: lambda_function.lambda_handler + runtime: python3.10 + - target: Audit + name: hello-world-python + runAsIamRole: arn:aws:iam::333333333333:role/LambdaExecutionRole + handler: lambda_function.lambda_handler + runtime: python3.10 + - target: ITSec + name: hello-world-python + runAsIamRole: arn:aws:iam::444444444444:role/LambdaExecutionRole + handler: lambda_function.lambda_handler + runtime: python3.10 + - target: Prod-West-2 + name: hello-world-python + runAsIamRole: arn:aws:iam::555555555555:role/LambdaExecutionRole + handler: lambda_function.lambda_handler + runtime: python3.10 +``` + +The S3 bucket has a policy that makes it accessible to multiple accounts in the same organization. diff --git a/content/en/reference/deployment/config-file/manifests.md b/content/en/reference/deployment/config-file/manifests.md index 3bb84af1..5960e4f0 100644 --- a/content/en/reference/deployment/config-file/manifests.md +++ b/content/en/reference/deployment/config-file/manifests.md @@ -1,9 +1,11 @@ --- -title: Manifests Config +title: Manifests Config (Kubernetes) description: > Declare the path to the Kubernetes manifests to use for your deployment. You can deploy a manifest to all targets or declare specific targets per manifest. --- +**Kubernetes Only** + ## Manifests section `manifests.` diff --git a/content/en/reference/deployment/config-file/strategies.md b/content/en/reference/deployment/config-file/strategies.md index 3c50ac38..ff715b30 100644 --- a/content/en/reference/deployment/config-file/strategies.md +++ b/content/en/reference/deployment/config-file/strategies.md @@ -345,6 +345,8 @@ All the queries must pass for the step as a whole to be considered a success. ## Blue/green fields +**Kubernetes Only** + ```yaml strategies: diff --git a/content/en/reference/deployment/config-file/targets.md b/content/en/reference/deployment/config-file/targets.md index 900cdbc8..0e7f1b5c 100644 --- a/content/en/reference/deployment/config-file/targets.md +++ b/content/en/reference/deployment/config-file/targets.md @@ -1,24 +1,41 @@ --- title: Targets Config description: > - Declare your deployment targets: account, namespace, and strategy to use. Configure target constraints such as `dependsOn`, `beforeDeployment`, and `afterDeployment` with pause, webhoook, and analysis conditions. + Declare your Kubernetes or AWS Lambda deployment targets. --- ## Targets config overview -In the `targets.` config block, you define where and how you want to deploy an app. You can specify multiple targets. Provide unique descriptive names for each environment to which you are deploying. +In the `targets.` config block, you define where and how you want to deploy your Kubernetes app or AWS Lambda function. -```yaml +You can specify multiple targets. Provide unique descriptive names for each target to which you are deploying. + +{{< cardpane >}} +{{< card code=true lang="yaml" header="AWS Lambda" >}} targets: : - account: - namespace: - strategy: - constraints: -``` + account: + deployAsIamRole: + region: + strategy: + constraints: +{{< /card >}} +{{< card code=true lang="yaml" header="Kubernetes" >}} +targets: + : + account: + namespace: + strategy: + constraints: +{{< /card >}} +{{< /cardpane >}} + +## Common fields -## Name +These fields are the same whether your target is AWS Lambda or a Kubernetes cluster. + +### Name `targets.`: A descriptive name for this deployment, such as the name of the environment you want to deploy to. @@ -30,53 +47,93 @@ targets: ... ``` -## Account (cluster) - -`targets..account`: The account name that a target Kubernetes cluster got assigned when you installed the Remote Network Agent (RNA) on it. Specifically, it is the value for the `agentIdentifier` parameter. Note that older versions of the RNA used the `agent-k8s.accountName` parameter. +### Strategy -This name must match an existing cluster because Armory CD-as-a-Service uses the identifier to determine which cluster to deploy to. +`targets..strategy`: This is the name of the strategy that you want to use to deploy your app. You define the strategy and its behavior in the `strategies` block. -For example, this snippet configures a deployment to an environment named `prod` that is hosted on a cluster named `prod-cluster-west`: +For example, this snippet configures a deployment to use the `canary-wait-til-approved` strategy: ```yaml targets: prod: account: prod-cluster-west -... + strategy: canary-wait-til-approved ``` -## Namespace +Read more about how this config is defined and used in the [strategies]({{< ref "reference/deployment/config-file/strategies" >}}) section. -`targets..namespace` +## AWS Lambda fields -Optional but recommended +```yaml +: + account: + deployAsIamRole: + region: +``` -The namespace on the target Kubernetes cluster that you want to deploy to. This field overrides any namespaces defined in your manifests. +### Account (AWS) -For example, this snippet overrides the namespace in your manifest and deploys the app to a namespace called `overflow`: +`targets..account`: A descriptive name for your AWS Account. + +```yaml +Prod-West-1: + account: armory-docs-dev +``` + +### Deploy as IAM Role + +`targets..deployAsIamRole`: The ARN of the [ArmoryRole]({{< ref "deployment/lambda/create-iam-role-lambda" + >}}) +that CD-as-a-Service assumes to deploy your function. + +```yaml +Prod-West-1: + deployAsIamRole: arn:aws:iam::111111111111:role/ArmoryRole +``` + +### AWS Region + +`targets..region`: The AWS Region to deploy your function to. + +```yaml +Prod-West-1: + region: us-west-1 +``` + +## Kubernetes fields + +### Account (cluster) + +`targets..account`: The account name that a target Kubernetes cluster got assigned when you installed the Remote Network Agent (RNA) on it. Specifically, it is the value for the `agentIdentifier` parameter. Note that older versions of the RNA used the `agent-k8s.accountName` parameter. + +This name must match an existing cluster because Armory CD-as-a-Service uses the identifier to determine which cluster to deploy to. + +For example, this snippet configures a deployment to an environment named `prod` that is hosted on a cluster named `prod-cluster-west`: ```yaml targets: prod: account: prod-cluster-west - namespace: overflow +... ``` -## Strategy +### Namespace -`targets..strategy`: This is the name of the strategy that you want to use to deploy your app. You define the strategy and its behavior in the `strategies` block. +`targets..namespace` -For example, this snippet configures a deployment to use the `canary-wait-til-approved` strategy: +Optional but recommended + +The namespace on the target Kubernetes cluster that you want to deploy to. This field overrides any namespaces defined in your manifests. + +For example, this snippet overrides the namespace in your manifest and deploys the app to a namespace called `overflow`: ```yaml targets: prod: account: prod-cluster-west namespace: overflow - strategy: canary-wait-til-approved ``` -Read more about how this config is defined and used in the [strategies]({{< ref "reference/deployment/config-file/strategies" >}}) section. ## Constraints @@ -88,6 +145,30 @@ Optional > Constraints are evaluated in parallel. +{{< tabpane text=true right=true >}} + {{% tab header="**Target**:" disabled=true /%}} + {{% tab header="AWS Lambda" %}} +```yaml +targets: + prod: + account: aws-docs-dev + deployAsIamRole: arn:aws:iam::111111111111:role/ArmoryRole + region: us-east-1 + strategy: canary-wait-til-approved + constraints: + dependsOn: [""] + beforeDeployment: + - pause: + untilApproved: true + - pause: + duration: + unit: + afterDeployment: + - runWebhook: + name: +``` + {{% /tab %}} + {{% tab header="Kubernetes" %}} ```yaml targets: prod: @@ -106,25 +187,52 @@ targets: - runWebhook: name: ``` + {{% /tab %}} + +{{< /tabpane >}} + ### Depends on Optional -`targets..constraints.dependsOn`: A comma-separated list of deployments that must finish before this deployment can start. You can use this option to sequence deployments. Deployments with the same `dependsOn` criteria execute in parallel. For example, you can make it so that a deployment to prod cannot happen until a staging deployment finishes successfully. +`targets..constraints.dependsOn`: A list of deployments that must finish before this deployment can start. You can use this option to sequence deployments. Deployments with the same `dependsOn` criteria execute in parallel. For example, you can make it so that a deployment to prod cannot happen until a staging deployment finishes successfully. The following example shows a deployment to `prod-west` that cannot start until the `dev-west` target finishes: +{{< tabpane text=true right=true >}} + {{% tab header="**Target**:" disabled=true /%}} + {{% tab header="AWS Lambda" %}} ```yaml targets: - prod: + prod-west: + account: aws-docs-dev + deployAsIamRole: arn:aws:iam::111111111111:role/ArmoryRole + region: us-west-1 + strategy: canary-wait-til-approved + constraints: + dependsOn: + - ITSec + - Audit +``` + {{% /tab %}} + {{% tab header="Kubernetes" %}} +```yaml +targets: + prod-west: account: prod-west namespace: overflow strategy: canary-wait-til-approved constraints: - dependsOn: ["dev-west"] + dependsOn: + - ITSec + - Audit ``` + {{% /tab %}} +{{< /tabpane >}} + + ### Before and after deployment Optional @@ -141,6 +249,31 @@ You can specify a pause that waits for a manual approval or a certain amount of **Pause until manual approval** +{{< tabpane text=true right=true >}} + {{% tab header="**Target**:" disabled=true /%}} + {{% tab header="AWS Lambda" %}} +```yaml +targets: + prod: + account: aws-docs-dev + deployAsIamRole: arn:aws:iam::111111111111:role/ArmoryRole + region: us-west-1 + strategy: canary-wait-til-approved + constraints: + dependsOn: ["dev-west"] + beforeDeployment: + - pause: + untilApproved: true + approvalExpiration: + duration: 60 + unit: seconds +``` + +- `pause.untilApproved`: Set to true +- `pause.approvalExpiration`: (Optional) Timeout configuration; when expired the ongoing deployment is cancelled + + {{% /tab %}} + {{% tab header="Kubernetes" %}} ```yaml targets: prod: @@ -161,9 +294,32 @@ targets: - `pause.untilApproved`: Set to true - `pause.requiresRoles`: (Optional) List of RBAC roles that can issue a manual approval - `pause.approvalExpiration`: (Optional) Timeout configuration; when expired the ongoing deployment is cancelled + + {{% /tab %}} + +{{< /tabpane >}} **Pause for a certain amount of time** +{{< tabpane text=true right=true >}} + {{% tab header="**Target**:" disabled=true /%}} + {{% tab header="AWS Lambda" %}} +```yaml +targets: + prod: + account: aws-docs-dev + deployAsIamRole: arn:aws:iam::111111111111:role/ArmoryRole + region: us-west-1 + strategy: canary-wait-til-approved + constraints: + dependsOn: ["dev-west"] + beforeDeployment: + - pause: + duration: 60 + unit: seconds +``` + {{% /tab %}} + {{% tab header="Kubernetes" %}} ```yaml targets: prod: @@ -177,14 +333,40 @@ targets: duration: 60 unit: seconds ``` + {{% /tab %}} + +{{< /tabpane >}} - `pause.duration` set to an integer value for the amount of time to wait before starting after the `dependsOn` condition is met. - `pause.unit` set to `seconds`, `minutes` or `hours` to indicate the unit of time to wait. #### Run a webhook -In the following example, before deploying to the `prod-cluster-west` target, CD-as-a-Service pauses deployment for manual approval by an Org Admin and also calls a webhook that sends a Slack notification. You declare the webhook in the [webhooks section] +In the following example, before deploying to the `prod-cluster-west` target, CD-as-a-Service pauses deployment for manual approval by an Org Admin and also calls a webhook that sends a Slack notification. You declare the webhook in the [webhooks section]({{< ref "reference/deployment/config-file/webhooks" >}}). +{{< tabpane text=true right=true >}} + {{% tab header="**Target**:" disabled=true /%}} + {{% tab header="AWS Lambda" %}} +```yaml +targets: + prod: + account: aws-docs-dev + deployAsIamRole: arn:aws:iam::111111111111:role/ArmoryRole + region: us-west-1 + strategy: canary-wait-til-approved + constraints: + dependsOn: ["staging"] + beforeDeployment: + - pause: + untilApproved: true + approvalExpiration: + duration: 24 + unit: hours + - runWebhook: + name: Send_Slack_Deployment_Approval_Required +``` + {{% /tab %}} + {{% tab header="Kubernetes" %}} ```yaml targets: prod: @@ -204,10 +386,17 @@ targets: - runWebhook: name: Send_Slack_Deployment_Approval_Required ``` + {{% /tab %}} + +{{< /tabpane >}} + + #### Analysis -In this example, CD-as-a-Service performs a [canary analysis]({{< ref "reference/canary-analysis-query" >}}) after deploying to the target. You declare your query in the [analysis section]{{< ref "reference/deployment/config-file/analysis" >}} and then add the name to the `queries` list. +**Kubernetes Only** + +In this example, CD-as-a-Service performs a [canary analysis]({{< ref "reference/canary-analysis-query" >}}) after deploying to the target. You declare your query in the [analysis section]({{< ref "reference/deployment/config-file/analysis" >}}) and then add the name to the `queries` list. ```yaml targets: @@ -229,11 +418,117 @@ targets: - avgCPUUsage ``` -## Example + +## AWS Lambda example + +{{< tabpane text=true right=true >}} + {{% tab header="**AWS Accounts**:" disabled=true /%}} + {{% tab header="Single" %}} +```yaml +targets: + Production-1: + account: arn:aws:iam::111111111111:role/ArmoryRole + constraints: + dependsOn: + - staging + deployAsIamRole: arn:aws:iam::111111111111:role/ArmoryRole + region: us-east-2 + strategy: allAtOnce + Production-2: + account: arn:aws:iam::111111111111:role/ArmoryRole + constraints: + dependsOn: + - staging + deployAsIamRole: arn:aws:iam::111111111111:role/ArmoryRole + region: us-west-1 + strategy: allAtOnce + staging: + account: arn:aws:iam::111111111111:role/ArmoryRole + constraints: + beforeDeployment: + - runWebhook: + name: Send_Slack_Deployment_Approval_Required + afterDeployment: + - runWebhook: + name: Integration_Tests + - pause: + untilApproved: true + deployAsIamRole: arn:aws:iam::111111111111:role/ArmoryRole + region: us-east-1 + strategy: allAtOnce +``` + {{% /tab %}} + {{% tab header="Multiple" %}} + +```yaml +targets: + Lab: + account: armory-lab + deployAsIamRole: "arn:aws:iam::111111111111:role/ArmoryRole" + region: us-west-2 + strategy: rollingDeployment + Staging: + account: armory-core + deployAsIamRole: "arn:aws:iam::222222222222:role/ArmoryRole" + region: us-west-2 + strategy: rollingDeployment + constraints: + dependsOn: + - Lab + afterDeployment: + - runWebhook: + name: Integration-Tests + Audit: + account: armory-audit + deployAsIamRole: "arn:aws:iam::333333333333:role/ArmoryRole" + region: us-west-2 + strategy: rollingDeployment + constraints: + dependsOn: + - Lab + afterDeployment: + - runWebhook: + name: Audit-Analysis + ITSec: + account: armory-itsec + deployAsIamRole: "arn:aws:iam::444444444444:role/ArmoryRole" + region: us-west-2 + strategy: rollingDeployment + constraints: + dependsOn: + - Lab + afterDeployment: + - runWebhook: + name: Security-Scans + Prod-West-2: + account: armory-prod + deployAsIamRole: "arn:aws:iam::555555555555:role/ArmoryRole" + region: us-west-2 + strategy: rollingDeployment + constraints: + dependsOn: + - Staging + - Audit + - ITSec + beforeDeployment: + - runWebhook: + name: Send-Slack-Deployment-Approval-Required + - pause: + untilApproved: true +``` + {{% /tab %}} + +{{< /tabpane >}} + + + +## Kubernetes example In this example, there are four targets: `dev`, `infosec`, `staging`, and `prod-west`. After you deploy code to `infosec` and `staging`, you want to run jobs against those targets. If either of those jobs fails, CD-as-a-Service does not deploy to `prod-west`. -`prod-west`'s `afterDeployment` conditions perform an analysis and call a webhook that sends a "deployment complete" notification. If the `analysis` condition fails, CD-as-a-Service rolls back the target deployment. +`prod-west`'s `afterDeployment` conditions perform an analysis and call a webhook that sends a "deployment complete" notification. + +>If the `analysis` condition fails, CD-as-a-Service does **not** roll back the prod-west deployment because the analysis condition is in an `afterdeployment` constraint. However, if you include the `analysis` step in your strategy and that `analysis` step fails, CD-as-a-Service **does** roll back the deployment. ```yaml targets: @@ -288,4 +583,3 @@ targets: namespace: cdaas-prod strategy: mycanary ``` - diff --git a/content/en/reference/deployment/config-file/traffic-management.md b/content/en/reference/deployment/config-file/traffic-management.md index 71641b0a..6f47600a 100644 --- a/content/en/reference/deployment/config-file/traffic-management.md +++ b/content/en/reference/deployment/config-file/traffic-management.md @@ -1,20 +1,37 @@ --- title: Traffic Management Config description: > - Declare Istio or Linkerd traffic management for all or specific targets. Configure Istio settings such as virtual service and destination rule. Configure Linkerd settings like root service, canary service, active service, and traffic split. + Declare AWS Lambda aliases. Declare Istio or Linkerd traffic management for all or specific Kubernetes targets. Configure Istio settings such as virtual service and destination rule. Configure Linkerd settings like root service, canary service, active service, and traffic split. --- ## Traffic management section `trafficManagement.` -You configure your service mesh per target in this section. If you omit the `target` entry, CD-as-a-Service applies the config to all targets. +## AWS Lambda + +You declare your AWS Lambda alias per target in this section. CD-as-a-Service uses [aliases](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html) when routing traffic from the previous version to the latest version of your function. ```yaml trafficManagement: - targets: [""] + alias: + - functionName: + aliasName: ``` +* `targets`: the list of targets using this alias +* `functionName`: This is the same value as `artifacts.functionName` and `providerOptions.lambda.name`. See {{< linkWithTitle "reference/deployment/config-file/artifacts.md" >}} for details on those sections. +* `aliasName`: The alias name, such as "live-version". Your function's alias must already exist in the AWS Lambda console. + +This example declares a traffic split canary strategy. You must declare your function's alias for each deployment target that uses the traffic split strategy. + +{{< readfile file="/includes/code/lambda-traffic-split-snippet.yaml" code="true" lang="yaml" >}} + +## Kubernetes + +You configure your service mesh per target in this section. + ### SMI targets `trafficManagement.targets.smi` diff --git a/content/en/troubleshooting/lambda.md b/content/en/troubleshooting/lambda.md new file mode 100644 index 00000000..7f1ec133 --- /dev/null +++ b/content/en/troubleshooting/lambda.md @@ -0,0 +1,86 @@ +--- +title: Troubleshoot AWS Lambda Deployment +linkTitle: AWS Lambda +weight: 1 +description: > + Solutions for issues you might encounter while deploying AWS Lambda functions using the Armory CD-as-a-Service. +--- + +## AWS Lamba Troubleshooting + +CD-as-a-Service returns errors thrown by AWS Lambda. If you encounter an error, be sure to check the AWS Lambda docs' [troubleshooting section](https://docs.aws.amazon.com/lambda/latest/dg/lambda-troubleshooting.html). + +## InvalidParameterValueException / PermanentRedirect + +```yaml +AWSCreateLambdaError: operation error +Lambda: CreateFunction, https response error +StatusCode: 400, +RequestID: ce98341e-8aa6-4c42-99e1-544245303295, +InvalidParameterValueException: Error occurred while GetObject. +S3 Error Code: PermanentRedirect. +S3 Error Message: The bucket is in this region: us-east-2. Please use this region to retry the request +``` + +You need to have an S3 bucket with your function archive in the region you want to deploy your function to. This is an AWS constraint. + +For example (same AWS Account): + +| Function | Target and Region | S3 Bucket Region | Bucket Name | Function Path | +|-----------------|-------------------|------------------|---------------|------------------------------------| +| hello-world.zip | Dev: us-east-1 | us-east-1 | lambda-us-east-1 | s3://lambda-us-east-1/hello-world.zip | +| hello-world.zip | Staging: us-east-2 | us-east-2 | lambda-us-east-1 | s3://lambda-us-east-2/hello-world.zip | +| hello-world.zip | Infosec: us-west-1 | us-west-1 | lambda-us-east-1 | s3://lambda-us-west-1/hello-world.zip | +| hello-world.zip | Prod: us-west-2 | us-west-2 | lambda-us-east-1 | s3://lambda-us-west-2/hello-world.zip | +| hello-world.zip | Prod: eu-central-1 | eu-central-1 | lambda-eu-central-1 | s3://lambda-eu-central-1/hello-world.zip | + +For more details, see the AWS Lambda [InvalidParameterValueException](https://docs.aws.amazon.com/lambda/latest/dg/troubleshooting-deployment.html#troubleshooting-deployment-InvalidParameterValueException1) and [PermanentRedirect](https://docs.aws.amazon.com/lambda/latest/dg/troubleshooting-deployment.html#troubleshooting-deployment-PermanentRedirect) troubleshooting docs. + +## ResourceConflictException + +```yaml +AWSUpdateLambdaError: operation error +Lambda: UpdateFunctionCode, https response error +StatusCode: 409, +RequestID: 8027c7ee-0762-4027-a238-2c636a716d48, +ResourceConflictException: Conflict due to concurrent requests on this function. Please try this request again. +``` + +You see this error when you have concurrent deployments to same region. + +For example, deploying this config results in a `ResourceConflictException` error. The `staging` and `audit` targets both deploy to `us-east-2` and depend on `dev`, so CD-as-a-Service deploys them concurrently. + +```yaml +version: v1 +kind: lambda +application: Sweet Potato Lambda +description: Sweet Potato facts from a Lambda function +deploymentConfig: + timeout: + unit: minutes + duration: 10 +targets: + dev: + account: armory-docs-dev + deployAsIamRole: arn:aws:iam::111111111111:role/ArmoryRole + region: us-east-1 + strategy: allAtOnce + staging: + account: armory-docs-dev + deployAsIamRole: arn:aws:iam::111111111111:role/ArmoryRole + region: us-east-2 + strategy: allAtOnce + constraints: + dependsOn: + - dev + audit: + account: armory-docs-dev + deployAsIamRole: arn:aws:iam::111111111111:role/ArmoryRole + region: us-east-2 + strategy: allAtOnce + constraints: + dependsOn: + - dev +``` + +The fix for this is to deploy `audit` to a different region or a different AWS Account. \ No newline at end of file