Merge pull request #2085 from github/deployment-guides/add-gke

Add GKE, Amazon ECS, and Azure App Service deployment guides
github · Dec 17, 2020 · 4ce9eab · 4ce9eab
2 parents 7266455 + 3aeac43
commit 4ce9eab
Show file tree

Hide file tree

Showing 4 changed files with 450 additions and 0 deletions.
diff --git a/content/actions/guides/deploying-to-amazon-elastic-container-service.md b/content/actions/guides/deploying-to-amazon-elastic-container-service.md
@@ -0,0 +1,150 @@
+---
+title: Deploying to Amazon Elastic Container Service
+intro: You can deploy to Amazon Elastic Container Service (ECS) as part of your continuous deployment (CD) workflows.
+product: '{% data reusables.gated-features.actions %}'
+versions:
+  free-pro-team: '*'
+  enterprise-server: '>=2.22'
+---
+
+{% data reusables.actions.enterprise-beta %}
+{% data reusables.actions.enterprise-github-hosted-runners %}
+
+### Introduction
+
+This guide explains how to use {% data variables.product.prodname_actions %} to build a containerized application, push it to [Amazon Elastic Container Registry (ECR)](https://aws.amazon.com/ecr/), and deploy it to [Amazon Elastic Container Service (ECS)](https://aws.amazon.com/ecs/).
+
+On every new release in your {% data variables.product.company_short %} repository, the {% data variables.product.prodname_actions %} workflow builds and pushes a new container image to Amazon ECR, and then deploys a new task definition to Amazon ECS.
+
+### Prerequisites
+
+Before creating your {% data variables.product.prodname_actions %} workflow, you will first need to complete the following setup steps for Amazon ECR and ECS:
+
+1. Create an Amazon ECR repository to store your images.
+
+   For example, using [the AWS CLI](https://aws.amazon.com/cli/):
+
+   {% raw %}```bash{:copy}
+   aws ecr create-repository \
+       --repository-name MY_ECR_REPOSITORY \
+       --region MY_AWS_REGION
+   ```{% endraw %}
+
+   Ensure that you use the same Amazon ECR repository name (represented here by `MY_ECR_REPOSITORY`) for the `ECR_REPOSITORY` variable in the workflow below.
+
+   Ensure that you use the same AWS region value for the `AWS_REGION` (represented here by `MY_AWS_REGION`) variable in the workflow below.
+
+2. Create an Amazon ECS task definition, cluster, and service.
+
+   For details, follow the [Getting started wizard on the Amazon ECS console](https://us-east-2.console.aws.amazon.com/ecs/home?region=us-east-2#/firstRun), or the [Getting started guide](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/getting-started-fargate.html) in the Amazon ECS documentation.
+
+   Ensure that you note the names you set for the Amazon ECS service and cluster, and use them for the `ECS_SERVICE` and `ECS_CLUSTER` variables in the workflow below.
+
+3. Store your Amazon ECS task definition as a JSON file in your {% data variables.product.company_short %} repository.
+
+   The format of the file should be the same as the output generated by:
+
+   {% raw %}```bash{:copy}
+   aws ecs register-task-definition --generate-cli-skeleton
+   ```{% endraw %}
+
+   Ensure that you set the `ECS_TASK_DEFINITION` variable in the workflow below as the path to the JSON file.
+
+   Ensure that you set the `CONTAINER_NAME` variable in the workflow below as the container name in the `containerDefinitions` section of the task definition.
+
+4. Create {% data variables.product.prodname_actions %} secrets named `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to store the values for your Amazon IAM access key.
+
+   For more information on creating secrets for {% data variables.product.prodname_actions %}, see "[Encrypted secrets](/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository)."
+
+   See the documentation for each action used below for the recommended IAM policies for the IAM user, and methods for handling the access key credentials.
+
+### Creating the workflow
+
+Once you've completed the prerequisites, you can proceed with creating the workflow.
+
+The following example workflow demonstrates how to build a container image and push it to Amazon ECR. It then updates the task definition with the new image ID, and deploys the task definition to Amazon ECS.
+
+Ensure that you provide your own values for all the variables in the `env` key of the workflow.
+
+{% raw %}
+```yaml{:copy}
+name: Deploy to Amazon ECS
+
+on:
+  release:
+    types: [ created ]
+
+env:
+  AWS_REGION: MY_AWS_REGION                   # set this to your preferred AWS region, e.g. us-west-1
+  ECR_REPOSITORY: MY_ECR_REPOSITORY           # set this to your Amazon ECR repository name
+  ECS_SERVICE: MY_ECS_SERVICE                 # set this to your Amazon ECS service name
+  ECS_CLUSTER: MY_ECS_CLUSTER                 # set this to your Amazon ECS cluster name
+  ECS_TASK_DEFINITION: MY_ECS_TASK_DEFINITION # set this to the path to your Amazon ECS task definition
+                                               # file, e.g. .aws/task-definition.json
+  CONTAINER_NAME: MY_CONTAINER_NAME           # set this to the name of the container in the
+                                               # containerDefinitions section of your task definition
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  deploy:
+    name: Deploy
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v1
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: $AWS_REGION
+
+      - name: Login to Amazon ECR
+        id: login-ecr
+        uses: aws-actions/amazon-ecr-login@v1
+
+      - name: Build, tag, and push image to Amazon ECR
+        id: build-image
+        env:
+          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
+          IMAGE_TAG: ${{ github.sha }}
+        run: |
+          # Build a docker container and
+          # push it to ECR so that it can
+          # be deployed to ECS.
+          docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .
+          docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG
+          echo "image=$ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG" >> $GITHUB_ENV
+
+      - name: Fill in the new image ID in the Amazon ECS task definition
+        id: task-def
+        uses: aws-actions/amazon-ecs-render-task-definition@v1
+        with:
+          task-definition: $ECS_TASK_DEFINITION
+          container-name: $CONTAINER_NAME
+          image: ${{ steps.build-image.outputs.image }}
+
+      - name: Deploy Amazon ECS task definition
+        uses: aws-actions/amazon-ecs-deploy-task-definition@v1
+        with:
+          task-definition: ${{ steps.task-def.outputs.task-definition }}
+          service: $ECS_SERVICE
+          cluster: $ECS_CLUSTER
+          wait-for-service-stability: true
+```
+{% endraw %}
+
+### Additional resources
+
+For more information on the services used in these examples, see the following documentation:
+
+* "[Security best practices in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)" in the Amazon AWS documentation.
+* Official AWS "[Configure AWS Credentials](https://github.com/aws-actions/configure-aws-credentials)" action.
+* Official AWS [Amazon ECR "Login"](https://github.com/aws-actions/amazon-ecr-login) action.
+* Official AWS [Amazon ECS "Render Task Definition"](https://github.com/aws-actions/amazon-ecs-render-task-definition) action.
+* Official AWS [Amazon ECS "Deploy Task Definition"](https://github.com/aws-actions/amazon-ecs-deploy-task-definition) action.
diff --git a/content/actions/guides/deploying-to-azure-app-service.md b/content/actions/guides/deploying-to-azure-app-service.md
@@ -0,0 +1,115 @@
+---
+title: Deploying to Azure App Service
+intro: You can deploy to Azure App Service as part of your continuous deployment (CD) workflows.
+product: '{% data reusables.gated-features.actions %}'
+versions:
+  free-pro-team: '*'
+  enterprise-server: '>=2.22'
+---
+
+{% data reusables.actions.enterprise-beta %}
+{% data reusables.actions.enterprise-github-hosted-runners %}
+
+### Introduction
+
+This guide explains how to use {% data variables.product.prodname_actions %} to build, test, and deploy an application to [Azure App Service](https://azure.microsoft.com/en-us/services/app-service/).
+
+Azure App Service can run web apps in several languages, but this guide demonstrates deploying an existing Node.js project.
+
+### Prerequisites
+
+Before creating your {% data variables.product.prodname_actions %} workflow, you will first need to complete the following setup steps:
+
+1. Create an Azure App Service plan.
+
+   For example, you can use the Azure CLI to create a new App Service plan:
+
+   ```bash{:copy}
+   az appservice plan create \
+       --resource-group MY_RESOURCE_GROUP \
+       --name MY_APP_SERVICE_PLAN \
+       --is-linux
+   ```
+
+   In the command above, replace `MY_RESOURCE_GROUP` with your pre-existing Azure Resource Group, and `MY_APP_SERVICE_PLAN` with a new name for the App Service plan.
+
+   See the Azure documentation for more information on using the [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/):
+
+   * For authentication, see "[Sign in with Azure CLI](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli)".
+   * If you need to create a new resource group, see "[az group](https://docs.microsoft.com/en-us/cli/azure/group?view=azure-cli-latest#az_group_create)."
+
+2. Create a web app.
+
+   For example, you can use the Azure CLI to create an Azure App Service web app with a node runtime:
+
+   ```bash{:copy}
+   az webapp create \
+       --name MY_WEBAPP_NAME \
+       --plan MY_APP_SERVICE_PLAN \
+       --resource-group MY_RESOURCE_GROUP \
+       --runtime "node|10.14"
+   ```
+
+   In the command above, replace the parameters with your own values, where `MY_WEBAPP_NAME` is a new name for the web app.
+
+3. Configure an Azure publish profile and create an `AZURE_WEBAPP_PUBLISH_PROFILE` secret.
+
+   Generate your Azure deployment credentials using a publish profile. For more information, see "[Generate deployment credentials](https://docs.microsoft.com/en-us/azure/app-service/deploy-github-actions?tabs=applevel#generate-deployment-credentials)" in the Azure documentation. 
+
+   In your {% data variables.product.prodname_dotcom %} repository, create a secret named `AZURE_WEBAPP_PUBLISH_PROFILE` that contains the contents of the publish profile. For more information on creating secrets, see "[Encrypted secrets](/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository)."
+
+### Creating the workflow
+
+Once you've completed the prerequisites, you can proceed with creating the workflow.
+
+The following example workflow demonstrates how to build, test, and deploy the Node.js project to Azure App Service.
+
+Ensure that you set `AZURE_WEBAPP_NAME` in the workflow `env` key to the name of the web app you created.
+
+{% raw %}
+```yaml{:copy}
+on:
+  release:
+    types: [created]
+
+env:
+  AZURE_WEBAPP_NAME: MY_WEBAPP_NAME   # set this to your application's name
+  AZURE_WEBAPP_PACKAGE_PATH: '.'      # set this to the path to your web app project, defaults to the repository root
+  NODE_VERSION: '10.x'                # set this to the node version to use
+
+jobs:
+  build-and-deploy:
+    name: Build and Deploy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Use Node.js ${{ env.NODE_VERSION }}
+        uses: actions/setup-node@v1
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: npm install, build, and test
+        run: |
+          # Build and test the project, then
+          # deploy to Azure Web App.
+          npm install
+          npm run build --if-present
+          npm run test --if-present
+
+      - name: 'Deploy to Azure WebApp'
+        uses: azure/webapps-deploy@v2
+        with:
+          app-name: ${{ env.AZURE_WEBAPP_NAME }}
+          publish-profile: ${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}
+          package: ${{ env.AZURE_WEBAPP_PACKAGE_PATH }}
+```
+{% endraw %}
+
+### Additional resources
+
+The following resources may also be useful:
+
+* For the original starter workflow, see [`azure.yml`](https://github.com/actions/starter-workflows/blob/master/ci/azure.yml) in the {% data variables.product.prodname_actions %} `starter-workflows` repository.
+* The action used to deploy the web app is the official Azure [`Azure/webapps-deploy`](https://github.com/Azure/webapps-deploy) action.
+* The "[Create a Node.js web app in Azure](https://docs.microsoft.com/en-us/azure/app-service/quickstart-nodejs)" quickstart in the Azure web app documentation demonstrates using VS Code with the [Azure App Service extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azureappservice).