diff --git a/content/actions/guides/deploying-to-amazon-elastic-container-service.md b/content/actions/guides/deploying-to-amazon-elastic-container-service.md new file mode 100644 index 000000000000..59b5b7bae253 --- /dev/null +++ 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 new file mode 100644 index 000000000000..3471b333ace0 --- /dev/null +++ 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). diff --git a/content/actions/guides/deploying-to-google-kubernetes-engine.md b/content/actions/guides/deploying-to-google-kubernetes-engine.md new file mode 100644 index 000000000000..ed8256ebbf05 --- /dev/null +++ b/content/actions/guides/deploying-to-google-kubernetes-engine.md @@ -0,0 +1,177 @@ +--- +title: Deploying to Google Kubernetes Engine +intro: You can deploy to Google Kubernetes Engine 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 Google Container Registry (GCR), and deploy it to Google Kubernetes Engine (GKE). + +GKE is a managed Kubernetes cluster service from Google Cloud that can host your containerized workloads in the cloud or in your own datacenter. For more information, see [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine). + +### Prerequisites + +Before you proceed with creating the workflow, you will need to complete the following steps for your Kubernetes project. This guide assumes the root of your project already has a `Dockerfile` and a Kubernetes Deployment configuration file. For an example, see [google-github-actions](https://github.com/google-github-actions/setup-gcloud/tree/master/example-workflows/gke). + +#### Creating a GKE cluster + +To create the GKE cluster, you will first need to authenticate using the `gcloud` CLI. For more information on this step, see the following articles: +- [`gcloud auth login`](https://cloud.google.com/sdk/gcloud/reference/auth/login) +- [`gcloud` CLI](https://cloud.google.com/sdk/gcloud/reference) +- [`gcloud` CLI and Cloud SDK](https://cloud.google.com/sdk/gcloud#the_gcloud_cli_and_cloud_sdk) + +For example: + +{% raw %} +```bash{:copy} +$ gcloud container clusters create $GKE_CLUSTER \ + --project=$GKE_PROJECT \ + --zone=$GKE_ZONE +``` +{% endraw %} + +#### Enabling the APIs + +Enable the Kubernetes Engine and Container Registry APIs. For example: + +{% raw %} +```bash{:copy} +$ gcloud services enable \ + containerregistry.googleapis.com \ + container.googleapis.com +``` +{% endraw %} + +#### Configuring a service account and storing its credentials + +This procedure demonstrates how to create the service account for your GKE integration. It explains how to create the account, add roles to it, retrieve its keys, and store them as a base64-encoded [encrypted repository secret](/actions/reference/encrypted-secrets) named `GKE_SA_KEY`. + +1. Create a new service account: + {% raw %} + ``` + $ gcloud iam service-accounts create $SA_NAME + ``` + {% endraw %} +1. Retrieve the email address of the service account you just created: + {% raw %} + ``` + $ gcloud iam service-accounts list + ``` + {% endraw %} +1. Add roles to the service account. Note: Apply more restrictive roles to suit your requirements. + {% raw %} + ``` + $ gcloud projects add-iam-policy-binding $GKE_PROJECT \ + --member=serviceAccount:$SA_EMAIL \ + --role=roles/container.admin \ + --role=roles/storage.admin + ``` + {% endraw %} +1. Download the JSON keyfile for the service account: + {% raw %} + ``` + $ gcloud iam service-accounts keys create key.json --iam-account=$SA_EMAIL + ``` + {% endraw %} +1. Store the project ID as a secret named `GKE_PROJECT`: + {% raw %} + ``` + $ export GKE_SA_KEY=$(cat key.json | base64) + ``` + {% endraw %} + +#### (Optional) Configuring kustomize +Kustomize is an optional tool used for managing YAML specs. After creating a _kustomization_ file, the workflow below can be used to dynamically set fields of the image and pipe in the result to `kubectl`. For more information, see [kustomize usage](https://github.com/kubernetes-sigs/kustomize#usage). + +### 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 GCR. It then uses the Kubernetes tools (such as `kubectl` and `kustomize`) to pull the image into the cluster deployment. + +{% raw %} +```yaml{:copy} +name: Build and Deploy to GKE + +on: + release: + types: [created] + +env: + PROJECT_ID: ${{ secrets.GKE_PROJECT }} + GKE_CLUSTER: cluster-1 # Add your cluster name here. + GKE_ZONE: us-central1-c # Add your cluster zone here. + DEPLOYMENT_NAME: gke-test # Add your deployment name here. + IMAGE: static-site + +jobs: + setup-build-publish-deploy: + name: Setup, Build, Publish, and Deploy + runs-on: ubuntu-latest + steps: + + - name: Checkout + uses: actions/checkout@v2 + + # Setup gcloud CLI + - uses: google-github-actions/setup-gcloud@v0.2.0 + with: + service_account_key: ${{ secrets.GKE_SA_KEY }} + project_id: ${{ secrets.GKE_PROJECT }} + + # Configure docker to use the gcloud command-line tool as a credential helper + - run: |- + gcloud --quiet auth configure-docker + + # Get the GKE credentials so we can deploy to the cluster + - uses: google-github-actions/get-gke-credentials@v0.2.1 + with: + cluster_name: ${{ env.GKE_CLUSTER }} + location: ${{ env.GKE_ZONE }} + credentials: ${{ secrets.GKE_SA_KEY }} + + # Build the Docker image + - name: Build + run: |- + docker build \ + --tag "gcr.io/$PROJECT_ID/$IMAGE:$GITHUB_SHA" \ + --build-arg GITHUB_SHA="$GITHUB_SHA" \ + --build-arg GITHUB_REF="$GITHUB_REF" \ + . + + # Push the Docker image to Google Container Registry + - name: Publish + run: |- + docker push "gcr.io/$PROJECT_ID/$IMAGE:$GITHUB_SHA" + + # Set up kustomize + - name: Set up Kustomize + run: |- + curl -sfLo kustomize https://github.com/kubernetes-sigs/kustomize/releases/download/v3.1.0/kustomize_3.1.0_linux_amd64 + chmod u+x ./kustomize + + # Deploy the Docker image to the GKE cluster + - name: Deploy + run: |- + ./kustomize edit set image gcr.io/PROJECT_ID/IMAGE:TAG=gcr.io/$PROJECT_ID/$IMAGE:$GITHUB_SHA + ./kustomize build . | kubectl apply -f - + kubectl rollout status deployment/$DEPLOYMENT_NAME + kubectl get services -o wide +``` +{% endraw %} + +### Additional resources + +For more information on the tools used in these examples, see the following documentation: + +* For the full starter workflow, see the ["Build and Deploy to GKE" workflow](https://github.com/actions/starter-workflows/blob/master/ci/google.yml). +* For more starter workflows and accompanying code, see Google's [{% data variables.product.prodname_actions %} example workflows](https://github.com/google-github-actions/setup-gcloud/tree/master/example-workflows/). +* The Kubernetes YAML customization engine: [Kustomize](https://kustomize.io/). +* "[Deploying a containerized web application](https://cloud.google.com/kubernetes-engine/docs/tutorials/hello-app)" in the Google Kubernetes Engine documentation. diff --git a/content/actions/guides/index.md b/content/actions/guides/index.md index b428505073c4..0ccacf47e77a 100644 --- a/content/actions/guides/index.md +++ b/content/actions/guides/index.md @@ -36,6 +36,14 @@ You can use {% data variables.product.prodname_actions %} to create custom conti {% link_in_list /building-and-testing-java-with-gradle %} {% link_in_list /building-and-testing-java-with-ant %} +### Creating custom continuous deployment workflows + +You can use {% data variables.product.prodname_actions %} to create custom continuous deployment (CD) workflows that deploy projects to a number of cloud partner ecosystems. + + {% link_in_list /deploying-to-amazon-elastic-container-service %} + {% link_in_list /deploying-to-azure-app-service %} + {% link_in_list /deploying-to-google-kubernetes-engine %} + ### Publishing software packages You can automate publishing software packages as part your continuous delivery (CD) workflow. Packages can be published to any package host and to {% data reusables.gated-features.packages %}.