nmasse-itix.threescale-cicd

ansible-cicd

通过红帽3scale API管理平台（3scale AMP）实现持续交付。

要求

此角色需要：

一个3scale API管理平台实例（托管或本地）
如果你计划使用OpenID连接身份验证，需要一个红帽SSO实例
两个APIcast网关（预发布和生产），可以是托管或自管
一个Swagger 2.0文件，描述你想要发布的API

所有组件都是通过API驱动，因此不需要SSH连接！

在控制节点上，需要jmespath库。如果尚未安装，可以使用以下命令安装：

pip install jmespath

还需要一个较新的Jinja版本（2.8）。你可以使用以下命令升级Jinja版本：

pip install -U Jinja2

如果你的控制节点运行在RHEL7上，您可以运行这个剧本来安装缺失的依赖项。

示例：在3scale SaaS上使用托管的APIcast网关部署API

如果你想在使用API密钥的SaaS 3scale实例上部署经典的“回显API”，可以分三步完成：

为你的回显API创建一个Swagger文件
构建你的清单文件
编写剧本
运行剧本！

首先，确保你的Swagger文件（api-swagger.yaml）包含所需的信息：

swagger: '2.0'
info:
  x-threescale-system-name: 'echo-api'
  title: 'Echo API'
  version: '1.0'
host: 'echo-api.3scale.net'
paths:
  /:
    get:
      operationId: Echo
      summary: '获取一个回显'
      description: '从服务器获取一个回显'
      x-threescale-smoketests-operation: true
      responses:
        200:
          description: '来自服务器的回显'
security:
- apikey: []
securityDefinitions:
  apikey:
    name: api-key
    in: header
    type: apiKey

在这个Swagger文件中，使用了以下字段：

x-threescale-system-name 用作3scale配置对象的基础系统名称。
title 用作服务定义的名称。
version 用于正确的版本控制，遵循semver标准。
host 是现有API后端的DNS名称。
operationId 字段用作方法/度量的系统名称。
summary 和 description 字段用于方法/度量的名称和描述。
x-threescale-smoketests-operation 用于标记某个操作可用于烟雾测试。该方法必须是幂等、只读且不带参数。如果没有方法被标记为烟雾测试，烟雾测试将被跳过。
security 和 securityDefinitions 用于确定公开API的安全方案。在此示例中，我们使用API密钥方案。

然后，编写inventory文件：

[all:vars]
ansible_connection=local

[threescale]
<TENANT>-admin.3scale.net

[threescale:vars]
threescale_cicd_access_token=<ACCESS_TOKEN>

清单文件的重要内容是：

需要在名为threescale的组中声明3scale管理员门户。
需要在threescale_cicd_access_token变量中设置3scale访问令牌。
由于不需要SSH连接（我们只使用3scale Admin API），因此整个清单的ansible_connection=local。

现在你可以编写剧本（deploy-api.yaml）：

- hosts: threescale
  gather_facts: no
  vars:
    threescale_cicd_openapi_file: 'api-swagger.yaml'
  roles:
  - nmasse-itix.threescale-cicd

主要部分是：

threescale_cicd_openapi_file 是在步骤1中定义的Swagger文件的路径。
使用nmasse-itix.threescale-cicd角色。
需要使用gather_facts: no，因为没有SSH连接到目标系统。

最后，你可以运行此剧本：

ansible-galaxy install nmasse-itix.threescale-cicd
ansible-playbook -i inventory deploy-api.yaml

清单

将要配置的3scale管理员门户是与包含此角色的剧本相关的。例如，在上述示例中，配置的3scale管理员门户将是<TENANT>-admin.3scale.net，因为主剧本指定了hosts: threescale，而threescale组仅包含一个主机：<TENANT>-admin.3scale.net。

如果您为3scale管理员门户指定多个主机，它们都将以完全相同的配置进行配置（适用于多站点部署）。

要连接到3scale管理员门户，您需要提供具有对账户管理API的读/写权限的访问令牌。您可以在主机级、组级或全局级别提供此令牌，使用变量threescale_cicd_access_token。

在主机级别，它的定义如下：

[threescale]
tenant1-admin.3scale.net threescale_cicd_access_token=123...456
tenant2-admin.3scale.net threescale_cicd_access_token=789...012

在组级别，您可以这样定义：

[threescale:vars]
threescale_cicd_access_token=123...456

[threescale]
tenant1-admin.3scale.net
tenant2-admin.3scale.net

您还可以全局定义，例如作为剧本变量：

- hosts: threescale
  vars:
    threescale_cicd_access_token: 123...456

红帽SSO实例（当前只能有一个）由threescale_cicd_sso_issuer_endpoint变量定义。

其语法为https://<client_id>:<client_secret>@hostname/auth/realms/<realm>。 client_id / client_secret 用于Zync与红帽SSO同步3scale应用。

示例：

threescale_cicd_sso_issuer_endpoint=https://3scale:123@sso.acme.corp/auth/realms/acme

APIcast实例由以下额外变量定义：

threescale_cicd_apicast_sandbox_endpoint
threescale_cicd_apicast_production_endpoint

示例：

threescale_cicd_apicast_sandbox_endpoint=http://api-test.acme.corp
threescale_cicd_apicast_production_endpoint=https://api.acme.corp

OpenAPI规范字段

此角色当前仅支持OpenAPI规范v2.0（又名Swagger 2.0）。

可以使用以下扩展字段的OpenAPI规范：

x-threescale-system-name，在info结构中用作基础，以构建3scale中配置对象的系统名称。
方法定义中的x-threescale-smoketests-operation用于将此操作标记为可用于烟雾测试。该方法需要是幂等、只读和无参数的。如果没有方法被标记为烟雾测试，烟雾测试将被跳过。

如果不能使用扩展字段（例如，您不想更改API合同），可以使用相应的额外变量：

threescale_cicd_api_base_system_name
threescale_cicd_openapi_smoketest_operation

下面是一个使用这些扩展字段的OpenAPI规范示例：

swagger: '2.0'
info:
  x-threescale-system-name: 'echo-api'
  title: 'Echo API'
  version: '1.0'
host: 'echo-api.3scale.net'
paths:
  /:
    get:
      operationId: Echo
      summary: '获取一个回显'
      description: '从服务器获取一个回显'
      x-threescale-smoketests-operation: true
      responses:
        200:
          description: '来自服务器的回显'
security:
- apikey: []
securityDefinitions:
  apikey:
    name: api-key
    in: header
    type: apiKey

也就是说，echo-api将被用作构建3scale服务定义的系统名称基础，而对/的GET请求将作为烟雾测试使用。

为了在没有OpenAPI扩展字段的情况下实现相同的效果，您需要传递以下额外变量：

threescale_cicd_api_base_system_name=echo-api
threescale_cicd_openapi_smoketest_operation=Echo # "GET /"方法的operationId

以下是使用的OpenAPI规范的标准字段。

在info部分：

title 用作3scale服务定义的显示名称。
version 用于正确的版本控制，遵循semver标准。
host 是现有API后端的DNS名称。

对于每个定义的方法：

operationId 字段用作相应方法/度量的系统名称。
summary 和 description 字段用于方法/度量的名称和描述。
security 和 securityDefinitions 用于确定公开API的安全方案。

为了使OpenAPI规范与3scale特性之间有一一对应的映射，对security / securityDefinitions结构施加了一些限制。具体来说，security结构中必须有一个且仅有一个安全要求。安全要求需要全局应用（而不是按方法进行）。

安全定义也有限制：您只能选择两种安全方案：

OAuth / OpenID连接
API密钥

3scale提出的应用密钥对方案在OpenAPI规范中没有相应的定义，目前不被该角色支持。

因此更具体地说，要通过API密钥保护API，请在您的OpenAPI规范文件中使用以下片段：

securityDefinitions:
  apikey:
    name: api-key
    in: header
    type: apiKey
security:
- apikey: []

当然，您可以通过更改name字段（在此示例中为api-key）来选择将用于发送API密钥的HTTP标头名称。

要通过OpenID连接保护，请在您的OpenAPI规范文件中使用以下片段：

securityDefinitions:
  oidc:
    type: oauth2
    flow: accessCode
    authorizationUrl: http://dummy/placeholder
    tokenUrl: http://dummy/placeholder
    scopes:
      openid: 获取OpenID连接令牌
security:
- oidc:
  - openid

您当然可以选择所需的OpenID连接流程：

implicit
password
application
accessCode

角色变量

本节详细介绍此角色中使用的所有变量。作为前言，此角色采用约定优于配置的方案。这意味着提供了合理的默认值和明确的命名方案。

`threescale_cicd_openapi_file`

指定要读取的OpenAPI规范文件。

语法： OpenAPI规范的完整路径，位于本地文件系统。避免使用相对路径，首选绝对路径。如果您需要读取相对于剧本的文件，请使用{{ playbook_dir }}占位符。
必需： 是
示例： /tmp/openapi.yaml 或 {{ playbook_dir }}/git/openapi.json

`threescale_cicd_openapi_file_format`

指定要读取的OpenAPI规范文件的格式（JSON或YAML）。

语法： JSON 或 YAML
必需： 否
默认值： YAML
示例： YAML

`threescale_cicd_api_system_name`

定义要配置的3scale服务的系统名称。

语法： 小写字母、数字 + 下划线
必需： 否
默认值： 如果未定义，系统名称取自threescale_cicd_api_base_system_name变量。此基础系统名称后面加上API主版本号，并在环境名称前面加上（仅当定义threescale_cicd_api_environment_name时）。
示例： dev_my_wonderful_service_1

`threescale_cicd_api_base_system_name`

用作计算threescale_cicd_api_system_name的基础。

语法： 小写字母、数字 + 下划线
必需： 否
默认值： 如果未定义，OpenAPI规范的x-threescale-system-name扩展字段或最后手段使用title字段进行清洗和使用。如果找不到title，将使用默认值API。如果找不到版本号，将使用0。
示例： my_wonderful_service

注意：如果同时设置了threescale_cicd_api_base_system_name和threescale_cicd_api_system_name，后者优先。

`threescale_cicd_wildcard_domain`

根据方案自动定义APIcast公共URL。

语法： DNS域后缀
必需： 否
默认值： 如果定义，则根据API系统名称计算threescale_cicd_apicast_sandbox_endpoint和threescale_cicd_apicast_production_endpoint。沙盒APIcast将是<system_name>-staging.<wildcard_domain>，而生产APIcast将是<system_name>.<wildcard_domain>。可以通过threescale_cicd_default_staging_suffix和threescale_cicd_default_production_suffix变量自定义预发布（-staging）和生产（空）后缀。

示例： 以下两个变量

threescale_cicd_wildcard_domain=acme.corp
threescale_cicd_api_base_system_name=my_wonderful_service

等价于：

threescale_cicd_apicast_sandbox_endpoint=https://my-wonderful-service-staging.acme.corp/
threescale_cicd_apicast_production_endpoint=https://my-wonderful-service.acme.corp/

`threescale_cicd_api_basepath`

定义后端API的basePath，覆盖OpenAPI规范的basePath字段。结果值用于定义3scale API网关的映射规则，将此基本路径添加到不同方法/操作的路径。

语法： URI部分，以/开头
必需： 否
默认值： OpenAPI规范的basePath字段。
示例： /api 或 /context

`threescale_cicd_api_backend_hostname`

定义后端主机名，覆盖OpenAPI规范的host字段。如果缺失，结果值用于定义threescale_cicd_private_base_url变量。

语法： 带可选端口的FQDN
必需： 否
默认值： OpenAPI规范的host字段。
示例： mybackend.acme.corp 或 mybackend.acme.corp:8080

`threescale_cicd_api_backend_scheme`

定义连接后端所使用的方案，覆盖OpenAPI规范的schemes字段。如果缺失，结果值用于定义threescale_cicd_private_base_url变量。

语法： http 或 https
必需： 否
默认值： OpenAPI规范scheme字段的第一个项目，如果缺失则默认为http。
示例： https

`threescale_cicd_private_base_url`

定义3scale私有基础URL。

语法： <schem>://<host>:<port>
必需： 否
默认值： <threescale_cicd_api_backend_scheme>://<threescale_cicd_api_backend_hostname>
示例： http://mybackend.acme.corp:8080

`threescale_cicd_apicast_policies_cors`

允许在APICast网关上启用CORS策略。如果您的API需要支持跨域和浏览器请求，并且未在OpenAPI规范文件中正确的路径中包含OPTIONS动词…

语法： 布尔值 yes 或 no
必需： 否
默认值： no
示例： 如果你想在APICast上激活CORS政策则为 yes

`threescale_cicd_openapi_smoketest_operation`

定义用于烟雾测试的OpenAPI规范方法。

语法： OpenAPI规范方法的operationId
必需： 否
默认值： 无。如果此变量未定义，并且OpenAPI规范中没有任何操作被标记为x-threescale-smoketests-operation，则跳过烟雾测试。
示例： GetName

`threescale_cicd_api_environment_name`

在服务名称前加上环境名称，以防止在同一3scale实例上多次部署相同API时发生名称冲突。

语法： 小写字母、数字 + 下划线
必需： 否
默认值： 无，未执行前缀。
示例： dev，test 或 prod

`threescale_cicd_validate_openapi`

验证OpenAPI规范文件是否符合官方模式。为此，使用go-swagger工具。

您可以在您的PATH某处预安装此工具。或者，您也可以通过threescale_cicd_goswagger_command额外变量指定swagger命令的完整路径。

如果缺少这个工具，它将自动从GitHub下载并安装到{{ threescale_cicd_local_bin_path }}。

语法： 布尔值（yes, no, true, false）
必需： 否
默认值： yes
示例：
- threescale_cicd_validate_openapi=no
- threescale_cicd_goswagger_command=/usr/local/bin/swagger
- threescale_cicd_local_bin_path=/tmp

`threescale_cicd_oicd_flows`

重写或更新此API支持的OAuth流的列表。

语法： 字符串数组（[ 'application', 'accessCode' ]）
必需： 否
默认值： OpenAPI规范文件中securityScheme对象的flow字段。
示例：
- threescale_cicd_oicd_flows="{{ [ 'application', 'accessCode' ] }}"（重写流列表）
- threescale_cicd_oicd_flows="{{ [ 'application', threescale_cicd_api_security_scheme.flow ] }}"（添加流）