Circleci.配置Cookbook
这Circleci.配置Cookbook是各个用例的集合（称为“食谱”），为您提供有关如何使用包括ORB的Circleci资源执行各种配置任务的详细的逐步说明。本指南及其关联部分将使您能够在Circleci平台上快速执行可重复的任务。
- 介绍
- 将更改部署到Amazon ECS
- 与Google Kubernetes Engine（GKE）互动
- Using Amazon Elastic Container Service for Kubernetes (Amazon EKS)
- 在Circleci作业中启用自定义松弛通知
- 选择使用流水线参数运行的工作流程
- 作业步骤的分支过滤
- 使用矩阵作业来运行多个操作系统测试
介绍
此页面及其关联的食谱描述了如何执行特定的配置任务。食谱包括代码片段和示例，让您自定义以适合您的项目。此类食谱中的每个配方都与单个任务相关，除了Circleci Orbs等Circleci资源之外，您可以使用自己的资源在Circleci平台上执行。
What are CircleCI orbs?
Circleci.orbs are configuration packages that enable you to get started with the CircleCI platform. Orbs enable you to share, standardize, and simplify configurations across your projects. You may also want to use orbs as a reference for configuration best practices.
Refer to theCircleci.ORBS注册表有关可用ORB的完整列表。
在2.1中使用现有的ORB。circleci/config.yml文件，用它调用它orbskey. The following example invokes the你好建立orb在里面circleci命名空间。
版：2.1orbs：hello：circleci/hello-build@x.y.z工作流程：“您好Workflow"：工作：-你好/ hello-buildFor more detailed information about CircleCI orbs, refer to the绿色原子介绍page.
Configure your environment for CircleCi pipelines and orbs
此类食谱中的大多数食谱呼叫版本2.1配置，管道和通常，Orbs。在使用提供的示例之前，您应该检查是否已为这些功能设置。以下注释和步骤会让您获得您需要的地方。
- In order to use pipelines features and orbs you must use
版2.1config. - 我们已经表明你需要指定的地方docker image for your jobwith
- If you wish to remain using
版2.0config, or are using a self-hosted installation of CircleCI Server, these recipes are still relevant because you can view the expanded orb source within theORBS注册表to see how the individual jobs and commands are built. - In the examples on this page that use orbs, you will notice that the orbs are versioned with tags, for example,
aws-s3: circleci/aws-s3@x.y.z。If you copy paste any examples you will need to editx.y.zto specify a version. You can find the available versions listed on the individual orb pages in theCircleci.ORBS注册表。 - 任何出现的物品
< >should be replaced with your own parameters.
将更改部署到Amazon ECS
Amazon Elastic Container Service（ECS）是一个可扩展的容器编排服务，使您可以支持Docker容器，并允许您在AWS上运行和缩放容器中的应用程序。通过使用Amazon ECS，您将能够在不安装和配置自己的容器编排软件的情况下使用此服务，从而消除了部署的复杂性，并确保您在Circleci平台上有一个简单而优化的容器部署。此配方向您展示如何使用Circleci Orbs将软件更改部署到Amazon ECS，但如果您希望有关亚马逊ECS服务的工作原理以及其底层组件和架构的更多详细信息，请参阅亚马逊ECS.文档。
设置环境变量
以下环境变量直接或通过上下文中的circleci设置：
aws_ECR_ACCOUNT_URL.MY_APP_PREFIXAWS_REGIONAWS_ACCESS_KEY_ID
If you need more information on how to set these environment variables, refer to theUsing Environment Variablescircleci文档的页面。
笔记：该CIRCLE_SHA1variable used in this example is built-in, so it is always available.
构建，推送和部署服务更新
配置A.AWS service update要从AWS ECR部署新建的图像，您可以使用ORBS保持配置尽可能简单：AWS-ECR.orb to build and push an updated image to ECR, and theAWS-ECS.ORB部署您的服务更新。
这following example shows building and pushing an image to AWS ECR and pushing that image as a service update to AWS ECS:
版：2.1# 2.1 config required to use orbsorbs：AWS-ECR.：circleci/aws-ecr@x.y.z.＃调用AWS ECR ORBAWS-ECS.：circleci/aws-ecs@x.y.z.# invoke the AWS ECS orb工作流程：构建和部署：工作：-AWS-ECR / Build-and-Push-Image：＃Orb内置作业repo：'${MY_APP_PREFIX}'tag：'$ {circle_sha1}'-AWS-ECS./deploy-service-update：＃Orb内置作业requires：-AWS-ECR / Build-and-Push-Imagefamily：'${MY_APP_PREFIX}-service'簇-name：'${MY_APP_PREFIX}-cluster'容器图像名称 - 更新：'container=${MY_APP_PREFIX}-service,tag=${CIRCLE_SHA1}'有关使用选项和ORB元素的完整列表，请参阅AWS-ECS ORB页面在Circleci Orbs注册表中。
Verify the AWS ECS service update
更新了Amazon ECS服务后，您可以验证是否已正确应用更新。要保持配置，请尽可能简单，请使用AWS CLI和ECS ORBS。这次，而不是使用ORB的内置作业来执行所需的过程，而来自ORB的命令用作作业定义中的步骤验证部署。
版：2.1orbs：aws-cli：circleci/aws-cli@x.y.z.AWS-ECS.：circleci/aws-ecs@x.y.z.工作：验证部署：docker：-图片：此示例说明了如何使用ORB安装和配置AWS CLI，检索任务定义以前部署了，然后verify该revision has been deployed using theverify-revision-is-deployed命令从AWS-ECSorb. Refer to theAWS ECR.示例ORB有关如何配置和推送图像到Amazon ECS的更多信息。
Find more detailed information in the CircleCI Orb Registry for the CircleCIAWS ECS.和AWS ECR.orbs.
与Google Kubernetes Engine（GKE）互动
这Google Kubernetes Engine (GKE) enables you to automate CI/CD strategies to quickly deploy code and application updates to your customers without requiring significant time to deliver these updates. Using GKE, CircleCI has leveraged this technology, along with development of a GKE-specific CircleCI orb, to enable you to interact with GKE within a specific job. Before working with GKE, you may wish to read Google’s technical documentation, which can be found on theGKE.文档页面。
Set environment variables
以下环境变量直接或通过上下文中的circleci设置：
gcloud_service_key.（必需的）GOOGLE_PROJECT_IDGOOGLE_COMPUTE_ZONE
If you need more information on how to set these environment variables, refer to theUsing Environment Variablescircleci文档的页面。
Creating and deleting clusters
使用Circleci.GKE.orb, you can perform complex actions with minimal configuration required. For example, once you have set the environment variable mentioned in the previous section, you can create a new GKE cluster using the following snippet:
版：2.1orbs：GKE.：circleci/gcp-gke@x.y.z工作流程：main：工作：-gke / create-cluster：簇：GCP测试要删除群集，您需要的只是：
版：2.1orbs：GKE.：circleci/gcp-gke@x.y.z工作流程：main：工作：-gke / delete-cluster：簇：GCP测试发布和将图像推出到GKE群集
使用Circleci GKE ORB使发布和向GKE群集推出码头图像非常简单，如下例所示。所有您需要的是Orbs内置命令发布和卷展栏图像嗨,ng with definitions for a few required parameters. For a full list of of parameters available for this job, check theGKE页面在Circleci Orbs注册表中。
版：2.1orbs：GKE.：circleci/gcp-gke@x.y.z工作流程：my-workflow：工作：-GKE./publish-and-rollout-image：簇：Using Amazon Elastic Container Service for Kubernetes (Amazon EKS)
Circleci.has developed a Kubernetes orb you can use in coordination with the Amazon Elastic Kubernetes Service (EKS) to perform the following tasks:
- Create an EKS cluster
- 创建Kubernetes部署
- Install Helm charts
- 更新容器图像
Before working with the CircleCI AWS-EKS orb, you may wish to review the specifics of theAWS-EKSORB在Circleci Orb注册表页面中。
创建EKS群集
使用Circleci.aws-eksORB，您可以使用下面显示的代码示例创建，测试和拆除EKS群集。
版：2.1orbs：aws-eks：circleci/aws-eks@x.y.z.Kubernetes.：circleci/kubernetes@x.y.z工作：测试-簇：executor：aws-eks/python3parameters：簇-name：description：|EKS群集的名称type：string脚步：-Kubernetes./install-AWS-EKS / UPDATE-KUBECONFIG-with验证者：簇-name：<< presides.cluster-name >>-跑：命令：|kubectl get servicesname：测试集群工作流程：deployment：工作：-aws-eks/create-cluster：簇-name：my-eks-demo-测试-簇：簇-name：my-eks-demorequires：-aws-eks/create-cluster-aws-eks/delete-cluster：簇-name：my-eks-demorequires：-测试-簇在此示例中，使用了两个ORB：内置作业和来自的命令aws-eksorb are used to create, test and then teardown a cluster. The built-ininstall命令从Kubernetes.ORB用于安装kubectl。
创建Kubernetes部署
您可能希望创建Kubernetes部署，这使您可以管理群集并在群集中执行不同的操作，包括以下功能：
- 更新群集中的资源
- update the Kubernetes configuration with the authenticator
- 更新容器图像
这code example below illustrates how you can create the Kubernetes deployment.
版：2.1orbs：aws-eks：circleci/aws-eks@x.y.z.Kubernetes.：circleci/kubernetes@x.y.z工作：创建部署：executor：aws-eks/python3parameters：簇-name：description：|EKS群集的名称type：string脚步：-checkout-AWS-EKS / UPDATE-KUBECONFIG-with验证者：簇-name：<< presides.cluster-name >>安装-Kubectl.：真的-Kubernetes./create-or-update-resource：获取 - 卷展栏状态：真的资源文件路径：测试s/nginx-deployment/deployment.yamlresource-name：部署/ nginx-deployment工作流程：deployment：工作：-aws-eks/create-cluster：簇-name：EKS-DEMO部署-创建部署：簇-name：EKS-DEMO部署requires：-aws-eks/create-cluster-AWS-eks /更新 - 容器图像：簇-name：EKS-DEMO部署container-image-updates：'nginx = nginx：1.9.1'后步：-Kubernetes /删除资源：资源名称：nginx-deploymentresource-types：deploymentwait：真的记录：真的requires：-创建部署resource-name：部署/ nginx-deployment-aws-eks/delete-cluster：簇-name：EKS-DEMO部署requires：-AWS-eks /更新 - 容器图像Install a Helm chart in your cluster
Helm是一个强大的应用程序包管理器，在Kubernetes集群的顶部运行，允许您使用Helm-Charts描述应用程序结构并使用简单命令管理结构。Helm使用称为图表的包装格式，这些文件是描述相关的Kubernetes资源集的文件集合。单个图表可用于部署简单的内容，如Memcached Pod，或者复杂，如具有HTTP服务器，数据库，缓存等的完整Web App Stack。
使用aws-eksORB您可以在Kubernetes集群上安装Helm，然后使用Orb的内置作业安装Helm图表。下面是一个代码示例，Wchich还通过在进程结束时删除释放和群集来清理：
版：2.1orbs：aws-eks：circleci/aws-eks@x.y.z.工作流程：deployment：工作：-aws-eks/create-cluster：簇-name：我的eks-helm-demo-aws-eks / install-helm-on-cluster：簇-name：我的eks-helm-demoEN.able-cluster-wide-admin-access：真的requires：-aws-eks/create-cluster-AWS-eks / Install-Helm-Chart：图表：稳定/格拉纳簇-name：我的eks-helm-demo释放名称：Grafana-释放requires：-aws-eks / install-helm-on-cluster-AWS-EKS / DELETE-HELM-RELEASE：簇-name：我的eks-helm-demo释放名称：Grafana-释放requires：-AWS-eks / Install-Helm-Chart-aws-eks/delete-cluster：簇-name：我的eks-helm-demorequires：-AWS-EKS / DELETE-HELM-RELEASE在Circleci作业中启用自定义松弛通知
Slack is a real-time collaboration application where team members can work together to perform routine tasks and projects through custom channels and workspaces. When using the CircleCI platform, you may find it useful to enable custom notifications with the Slack app based on specific team needs and requirements.
Notifying a Slack channel of pending approval
这Circleci.Slack orbEN.ables you to create different notifications and messages that can be delivered to your desired recipients. One type of notification you can create is an “approval” notification that alerts your recipients that a specific approval is pending. The example below illustrates how you can create this approval notification in a CircleCI job:
版：2.1orbs：slack：circleci/slack@x.y.z.工作流程：your-workflow：工作：-松弛/批准通知：message：待批准Webhook.：Webhook.In the above example, note that you first need to invoke thecircleci/slack@x.y.z.orb before running your workflow, which then enables you to send your notification with its associatedmessage和Webhook.。
这re are several parameters for you to customize your Slack notifications that aren’t shown here. For more detailed information about this orb and its functionality, refer to the Slack orb in theCircleci.Orb Registry。
Notifying a Slack channel with custom messages
您可以使用Circleci Slack ORB创建的另一种通知是具有由您创建的自定义消息的通知。当您想要向您的收件人提供特定于工作流程，作业或项目的收件人提供详细消息时，此类通知非常有用。
下面显示的示例详细信息如何创建自定义消息，该消息将为用户提供特定的Slack通道。
版：2.1orbs：slack：circleci/slack@x.y.z.工作：建造：docker：-图片：In this example, the Slack orb commandnotifyis used, along with the following parameters to create a custom notification:
- Specify the
color消息中的文本。 - Identify the recipients (
提到）消息。 - Provide the text in the
message你想要交付。 - Specify the
Webhook.对于邮件 - 看到这个guidefor more on creating Slack webhooks.
Sending a status alert at the end of a job based on success or failure
You may also send a status alert at the end of a job to your recipients. Note that this status alert must be the last step in a job.
下面的示例显示了如何在作业结束时发送状态警报。
版：2.1orbs：slack：circleci/slack@x.y.z.工作：建造：docker：-图片：Notice in the example that the job is run and a Slack status alert is sent to your recipients (USERID1, USERID2) if the job has failed.
有关此ORB及其功能的更多详细信息，请参阅中间的SLACK ORBCircleci.Orb Registry。
选择使用流水线参数运行的工作流程
You might find that you want to be able to trigger a specific workflow to run, manually, using the API, but still run a workflow on every push to your project. To achieve this, usepipeline parameters决定要运行的工作流程。
这following example defaults to running the建造工作流程，但允许控制使用API运行哪些其他工作流程：
版：2.1parameters：action：type：EN.umEN.um：[建造那report]默认：建造工作：建造：machine：真的脚步：-checkout-跑：./run-tests.sh.report：machine：真的脚步：-checkout-跑：./create-report.sh.工作流程：建造：when：equal：[建造那<<管道.Parameters.Action >>]工作：-建造report：when：equal：[report那<<管道.Parameters.Action >>]工作：-report这action参数将默认为建造on pushes to the project. Below is an example of supplying a different value toaction使用API v2Trigger a New PipelineEN.dpoint to select a different workflow to run, in this example, the workflow namedreport会跑。记得替代投射吧有你的价值观。
卷曲-X//www.drag240sx.com/api/v2/project/{投射吧}/管道\-H'Content-Type: application/json'\-H'Accept: application/json'\-H'Circle-Token: API_KEY'\-D.”{parameters": { "action": report } }'For more information on using API v2 endpoints, see theAPI.Reference Documentation和API开118金宝博娱乐城发人员指导工作示例。
作业步骤的分支过滤
分支过滤以前仅适用于工作流，但使用编译时逻辑语句，您还可以实现作业步骤的分支过滤。
以下示例使用该示例显示pipeline valuepipeline.git.branchto controlwhena step should run. In this case the step跑：回声“我在主人上”only runs when the commit is on the master branch:
版：2.1工作：我的工作：docker：-图片：CIMG /底座：稳定auth：username：mydockerhub-user密码：$ dockerhub_password.＃上下文/项目UI ENV-VAR参考脚步：-checkout-when：健康）状况：equal：[掌握那<< pipeline.git.branch >>]脚步：-跑：echo "I am on master"工作流程：my-workflow：工作：-我的工作使用矩阵作业来运行多个操作系统测试
Using matrix jobs is a good way to run a job multiple times with different arguments, using parameters. There are many uses for this, including testing on multiple operating systems and against different language/library versions.
In the following example the测试作业在Linux，Windows和MacOS环境中运行，使用两个不同版本的节点。每次运行测试job different parameters are passed to set both the OS and the node version:
版：2.1orbs：节点：circleci/node@4.0.0赢得：circleci/windows@2.2.0executors：linux：＃使用节点基础图像的Linux执行程序docker：-图片：CIMG / node.auth：username：mydockerhub-user密码：$ dockerhub_password.＃上下文/项目UI ENV-VAR参考赢得dows：赢得/default# windows executor - uses the default executor from the windows orbmacos：# macos executor using xcode 11.6macos：Xcode.：11.6工作：测试：parameters：OS.：type：executor节点版本：type：stringexecutor：<<参数>>脚步：-checkout-节点/install：节点版本：<<参数.Node-version >>安装纱线：真的-跑：yarn test工作流程：all-tests：工作：-测试：矩阵：parameters：OS.：[linux那赢得dows那macos]节点版本：[“13.13.0"那“14.0.0“]此矩阵的扩展版本运行以下作业列表all-testsworkflow:
- Test-13.13.0-Linux - Test-14.0.0-Linux - Test-13.13.0-Windows - Test-14.0.0-Windows - Test-13.13.0-MacOS - Test-14.0.0-MacOSFor full details of the matrix jobs specification, see the配置Reference。