使用声明式配置

从声明式配置创建的资源的限制
创建声明式配置
声明式配置示例
声明式配置故障排除
其他资源

使用声明式配置，您可以通过将配置存储在存储库中的文件中并将它们应用于系统来更新配置。例如，如果您使用的是GitOps工作流，则声明式配置非常有用。您目前可以在Red Hat Advanced Cluster Security for Kubernetes (RHACS)中对身份验证和授权资源（例如身份验证提供程序、角色、权限集和访问范围）使用声明式配置。

要使用声明式配置，您可以创建包含有关身份验证和授权资源的配置信息的YAML文件。这些文件或配置通过在Central安装期间使用挂载点添加到RHACS。有关在安装RHACS时配置挂载点的更多信息，请参阅“其他资源”部分中的安装文档。

与声明式配置一起使用的配置文件存储在ConfigMap或密钥中，具体取决于资源类型。出于更高的安全性考虑，请将身份验证提供程序的配置存储在密钥中。您可以将其他配置存储在ConfigMap中。

单个ConfigMap或密钥可以包含多种资源类型的多个配置。这允许您限制Central实例的卷挂载数量。

从声明式配置创建的资源的限制

因为资源可以引用其他资源（例如，角色可以同时引用权限集和访问范围），所以以下引用限制适用

声明式配置只能引用同样以声明式方式创建的资源或系统 RHACS 资源；例如，Admin 或 Analyst 系统角色或权限集之类的资源。
资源间的全部引用都使用名称来标识资源；因此，相同资源类型中的所有名称都必须唯一。
由声明式配置创建的资源只能通过修改声明式配置文件来修改或删除。您无法使用 RHACS 门户或 API 来更改这些资源。

创建声明式配置

使用 roxctl 创建存储配置的 YAML 文件，从这些文件创建配置映射，并应用配置映射。

先决条件

您在安装 Central 时已添加了配置映射或密钥的挂载点。在此示例中，配置映射称为“declarative-configs”。有关更多信息，请参阅“其他资源”部分中列出的安装文档。

步骤

输入以下命令创建权限集。此示例创建名为“restricted”的权限集，并将其保存为permission-set.yaml文件。它为Administration资源设置读写访问权限，为Access资源设置读取访问权限。

$ roxctl declarative-config create permission-set \
--name="restricted" \
--description="Restriction permission set that only allows \
access to Administration and Access resources" \
--resource-with-access=Administration=READ_WRITE_ACCESS \
--resource-with-access=Access=READ_ACCESS > permission-set.yaml

输入以下命令创建允许访问Administration和Access资源的角色。此示例创建名为“restricted”的角色，并将其保存为role.yaml文件。

$ roxctl declarative-config create role \
--name="restricted" \
--description="Restricted role that only allows access to Administration and Access" \
--permission-set="restricted" \
--access-scope="Unrestricted" > role.yaml

输入以下命令，从前面步骤中创建的两个 YAML 文件创建配置映射。此示例创建declarative-configurations配置映射。
```
$ kubectl create configmap declarative-configurations \ (1)
--from-file permission-set.yaml --from-file role.yaml \
-o yaml --namespace=stackrox > declarative-configs.yaml
```
1 对于 OpenShift Container Platform，请使用oc create。
输入以下命令应用配置映射
```
$ kubectl apply -f declarative-configs.yaml (1)
```
1 对于 OpenShift Container Platform，请使用oc apply。

应用配置映射后，从 Central 提取的配置信息将创建资源。

尽管观察间隔为 5 秒（如下段所述），但将更改从配置映射传播到 Central 挂载点可能会有延迟。

您可以配置以下间隔以指定声明式配置如何与 Central 交互
- 配置观察间隔：Central 检查更改的间隔为每 5 秒。您可以使用ROX_DECLARATIVE_CONFIG_WATCH_INTERVAL环境变量配置此间隔。
- 协调间隔：默认情况下，声明式配置与 Central 的协调每 20 秒发生一次。您可以使用ROX_DECLARATIVE_CONFIG_RECONCILE_INTERVAL环境变量配置此间隔。

使用声明式配置创建身份验证和授权资源后，您可以在 RHACS Web 门户的**访问控制**页面中查看它们。如果资源是使用声明式配置创建的，则**来源**字段将显示Declarative。

您不能在 RHACS Web 门户中编辑从声明式配置创建的资源。您必须直接编辑配置文件才能对这些资源进行更改。

您可以通过导航到**平台配置**→**系统健康**并滚动到**声明式配置**部分来查看声明式配置的状态。

声明式配置示例

您可以使用以下示例作为指南来创建声明式配置。使用roxctl declarative-config lint命令验证您的配置是否有效。

声明式配置身份验证提供程序示例

name: A sample auth provider
minimumRole: Analyst (1)
uiEndpoint: central.custom-domain.com:443 (2)
extraUIEndpoints: (3)
    - central-alt.custom-domain.com:443
groups: (4)
    - key: email (5)
      value: [email protected]
      role: Admin (6)
    - key: groups
      value: reviewers
      role: Analyst
requiredAttributes: (7)
    - key: org_id
      value: "12345"
claimMappings: (8)
    - path: org_id
      value: my_org_id
oidc: (9)
    issuer: sample.issuer.com (10)
    mode: auto (11)
    clientID: CLIENT_ID
    clientSecret: CLIENT_SECRET
clientSecret: CLIENT_SECRET
iap: (12)
    audience: audience
saml: (13)
    spIssuer: sample.issuer.com
    metadataURL: sample.provider.com/metadata
saml: (14)
    spIssuer: sample.issuer.com
    cert: | (15)
    ssoURL: saml.provider.com
    idpIssuer: idp.issuer.com
userpki:
    certificateAuthorities: | (16)
    certificate (17)
openshift: (18)
    enable: true

1	标识将默认分配给任何登录用户的最低角色。如果留空，则值为`None`。
2	使用 Central 实例的用户界面端点。
3	如果您的 Central 实例公开到不同的端点，请在此处指定它们。
4	这些字段根据用户的属性将用户映射到特定角色。
5	密钥可以是身份验证提供程序返回的任何声明。
6	标识授予用户的角色。您可以使用默认角色或声明式创建的角色。
7	可选：如果需要身份验证提供程序返回的属性；例如，如果受众限于特定组织或组，则使用这些字段。
8	可选：如果应将身份提供程序返回的声明映射到自定义声明，则使用这些字段。
9	此部分仅适用于 OpenID Connect (OIDC) 身份验证提供程序。
10	标识令牌的预期发行者。
11	标识 OIDC 回调模式。可能的值为`auto`、`post`、`query`和`fragment`。首选值为`auto`。
12	此部分仅适用于 Google Identity-Aware Proxy (IAP) 身份验证提供程序。
13	此部分仅适用于 Security Assertion Markup Language (SAML) 2.0 动态配置身份验证提供程序。
14	此部分仅适用于 SAML 2.0 静态配置身份验证提供程序。
15	以隐私增强邮件 (PEM) 格式包含证书。
16	此部分仅适用于使用用户证书进行身份验证。
17	以 PEM 格式包含证书。
18	此部分仅适用于 OpenShift Auth 身份验证提供程序。

声明式配置权限集示例

name: A sample permission set
description: A sample permission set created declaratively
resources:
- resource: Integration (1)
  access: READ_ACCESS  (2)
- resource: Administration
  access: READ_WRITE_ACCESS

1	有关支持的资源的完整列表，请转到访问控制→权限集。
2	访问权限可以是`READ_ACCESS`或`READ_WRITE_ACCESS`。

声明式配置访问范围示例

name: A sample access scope
description: A sample access scope created declaratively
rules:
    included:
        - cluster: secured-cluster-A (1)
          namespaces:
            - namespaceA
        - cluster: secured-cluster-B (2)
    clusterLabelSelectors:
        - requirements:
        - requirements:
          - key: kubernetes.io/metadata.name
            operator: IN (3)
            values:
            - production
            - staging
            - environment

1	标识一个集群，其中仅包含访问范围内的特定命名空间。
2	标识一个集群，其中访问范围包含所有命名空间。
3	标识要用于标签选择的运算符。有效值为`IN`、`NOT_IN`、`EXISTS`和`NOT_EXISTS`。

声明式配置角色示例

name: A sample role
description: A sample role created declaratively
permissionSet: A sample permission set (1)
accessScope: Unrestricted (2)

1	权限集的名称；可以是系统权限集之一或声明式创建的权限集。
2	访问范围的名称；可以是系统访问范围之一或声明式创建的访问范围。

声明式配置疑难解答

您可以使用**平台配置**→**系统健康**页面**声明式配置**部分中显示的错误消息来帮助进行故障排除。roxctl declarative-config命令还包含一个lint选项，用于验证配置文件并帮助您检测错误。

**平台配置**→**系统健康**页面**声明式配置**部分中显示的错误消息提供有关声明式配置问题的相关信息。声明式配置的问题可能是由以下条件引起的：

配置文件的格式不是有效的 YAML。
配置文件包含无效值，例如权限集中的无效访问权限。
存在无效的存储约束，例如资源名称不唯一或配置包含对资源的无效引用。

要验证配置文件、检查配置文件中的错误，并确保在创建和更新配置文件时不存在无效的存储约束，请使用roxctl declarative-config lint命令。

要在删除过程中排查存储约束问题，请检查资源是否已被标记为Declarative Orphaned。这表示某个资源引用的声明式配置已被删除（例如，如果被某个角色引用的权限集的声明式配置已被删除）。要纠正此错误，请编辑资源以指向新的权限集，或恢复已删除的声明式配置。