本章论述了如何使用自定义资源(CR)进行红帽构建的 Keycloak 部署的高级配置。
许多服务器选项都作为 Keycloak CR 中的第一类会面字段公开。CR 的结构基于红帽构建的 Keycloak 的配置结构。例如,若要配置服务器的 https-port
,请在 CR 中遵循类似模式,并使用 httpsPort
字段。以下示例是复杂的服务器配置,但它演示了服务器选项和 Keycloak CR 之间的关系:
apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
name: example-kc
spec:
db:
vendor: postgres
usernameSecret:
name: usernameSecret
key: usernameSecretKey
passwordSecret:
name: passwordSecret
key: passwordSecretKey
host: host
database: database
port: 123
schema: schema
poolInitialSize: 1
poolMinSize: 2
poolMaxSize: 3
http:
httpEnabled: true
httpPort: 8180
httpsPort: 8543
tlsSecret: my-tls-secret
hostname:
hostname: https://my-hostname.tld
admin: https://my-hostname.tld/admin
strict: false
backchannelDynamic: true
features:
enabled:
- docker
- authorization
disabled:
- admin
- step-up-authentication
transaction:
xaEnabled: false
apiVersion : k8s.keycloak.org/v2alpha1
kind : Keycloak
metadata :
name : example- kc
spec :
db :
vendor : postgres
usernameSecret :
name : usernameSecret
key : usernameSecretKey
passwordSecret :
name : passwordSecret
key : passwordSecretKey
host : host
database : database
port : 123
schema : schema
poolInitialSize : 1
poolMinSize : 2
poolMaxSize : 3
http :
httpEnabled : true
httpPort : 8180
httpsPort : 8543
tlsSecret : my- tls- secret
hostname :
hostname : https: //my- hostname.tld
admin : https: //my- hostname.tld/admin
strict : false
backchannelDynamic : true
features :
enabled :
- docker
- authorization
disabled :
- admin
- step- up- authentication
transaction :
xaEnabled : false
Copy to Clipboard
Copied!
Toggle word wrap
Toggle overflow
有关选项列表,请参阅 Keycloak CRD。有关配置选项的详情,请查看 所有配置 。
一些专家服务器选项作为 Keycloak CR 中的专用字段不可用。以下是省略的字段示例:
需要深入了解底层红帽构建的 Keycloak 实现的字段
与 OpenShift 环境无关的字段
供应商配置的字段,因为它们基于使用的供应商实现动态
Keycloak CR 的 additionalOptions
字段可让红帽构建 Keycloak 以键值对的形式接受任何可用的配置。您可以使用此字段包含 Keycloak CR 中省略的任何选项。有关配置选项的详情,请查看 所有配置 。
这些值可以表示为纯文本字符串或 Secret 对象引用,如下例所示:
apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
name: example-kc
spec:
...
additionalOptions:
- name: spi-connections-http-client-default-connection-pool-size
secret: # Secret reference
name: http-client-secret # name of the Secret
key: poolSize # name of the Key in the Secret
- name: spi-email-template-mycustomprovider-enabled
value: true # plain text value
apiVersion : k8s.keycloak.org/v2alpha1
kind : Keycloak
metadata :
name : example- kc
spec :
...
additionalOptions :
- name : spi- connections- http- client- default- connection- pool- size
secret :
name : http- client- secret
key : poolSize
- name : spi- email- template- mycustomprovider- enabled
value : true
Copy to Clipboard
Copied!
Toggle word wrap
Toggle overflow
Secret References 由 Keycloak CR 中的一些专用选项使用,如 tlsSecret
,或作为 additionalOptions
中的值。
同样,ConfigMap 引用也被选项(如 configMapFile
)使用。
在指定 Secret 或 ConfigMap 参考时,请确保包含引用密钥的 Secret 或 ConfigMap 存在于与引用它的 CR 相同的命名空间中。
Operator 每分钟会轮询大约一分钟,以更改引用的 Secret 或 ConfigMap。当检测到有意义的更改时,Operator 会执行红帽构建的 Keycloak Deployment 的滚动重启来获取更改。
CR 的 unsupported
字段包含没有完全测试且技术预览的高实验配置选项。
Pod 模板是一种原始 API 表示,用于 Deployment 模板。如果用例的 CR 的顶层没有支持的字段,则此字段是一个临时解决方案。
Operator 将提供的模板的字段与 Operator 为特定 Deployment 生成的值合并。使用此功能,您可以访问高级别的自定义。但是,没有保证 Deployment 将按预期工作。
以下示例演示了注入标签、注解、卷和卷挂载:
apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
name: example-kc
spec:
...
unsupported:
podTemplate:
metadata:
labels:
my-label: "keycloak"
spec:
containers:
- volumeMounts:
- name: test-volume
mountPath: /mnt/test
volumes:
- name: test-volume
secret:
secretName: keycloak-additional-secret
apiVersion : k8s.keycloak.org/v2alpha1
kind : Keycloak
metadata :
name : example- kc
spec :
...
unsupported :
podTemplate :
metadata :
labels :
my-label : "keycloak"
spec :
containers :
- volumeMounts :
- name : test- volume
mountPath : /mnt/test
volumes :
- name : test- volume
secret :
secretName : keycloak- additional- secret
Copy to Clipboard
Copied!
Toggle word wrap
Toggle overflow
Red Hat build of Keycloak 和 Red Hat build of Keycloak Operator 提供了最佳的生产环境就绪体验。但是,在开发阶段,您可以禁用关键安全功能。
特别是,您可以禁用主机名和 TLS,如下例所示:
apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
name: example-kc
spec:
...
http:
httpEnabled: true
hostname:
strict: false
apiVersion : k8s.keycloak.org/v2alpha1
kind : Keycloak
metadata :
name : example- kc
spec :
...
http :
httpEnabled : true
hostname :
strict : false
Copy to Clipboard
Copied!
Toggle word wrap
Toggle overflow
Keycloak CR 允许指定资源选项来管理红帽构建的 Keycloak 容器的计算资源。
它提供通过 Keycloak CR 独立请求和限制资源的功能,以及通过 Realm Import CR 为 realm 导入作业进行隔离。
如果没有指定值,默认 请求内存
设置为 1700MiB
,限制
内存设置为 2GiB
。根据红帽构建的 Keycloak 内存管理深度分析来选择这些值。
如果没有在 Realm Import CR 中指定值,它将回退到 Keycloak CR 中指定的值,或者返回上述定义的默认值。
您可以根据要求指定自定义值,如下所示:
apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
name: example-kc
spec:
...
resources:
requests:
cpu: 1200m
memory: 896Mi
limits:
cpu: 6
memory: 3Gi
apiVersion : k8s.keycloak.org/v2alpha1
kind : Keycloak
metadata :
name : example- kc
spec :
...
resources :
requests :
cpu : 1200m
memory : 896Mi
limits :
cpu : 6
memory : 3Gi
Copy to Clipboard
Copied!
Toggle word wrap
Toggle overflow
此外,红帽构建的 Keycloak 容器通过提供堆大小的相对值,从而更有效地管理堆大小。它可以通过提供某些 JVM 选项来实现。
如需了解更多详细信息,请参阅 在容器中运行红帽构建的 Keycloak 。
您可以通过 Keycloak CR 控制服务器 Pod 调度的一些方面。scheduling 小节会公开可选的标准 Kubernetes 关联性、容限、拓扑分布约束和优先级类名称,以微调服务器 Pod 的调度和放置。
使用所有调度字段的示例:
apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
name: example-kc
spec:
scheduling:
priorityClassName: custom-high
affinity:
podAffinity:
preferredDuringSchedulingIgnoredDuringExecution:
- podAffinityTerm:
labelSelector:
matchLabels:
app: keycloak
app.kubernetes.io/managed-by: keycloak-operator
app.kubernetes.io/component: server
topologyKey: topology.kubernetes.io/zone
weight: 10
tolerations:
- key: "some-taint"
operator: "Exists"
effect: "NoSchedule"
topologySpreadConstraints:
- maxSkew: 1
topologyKey: kubernetes.io/hostname
whenUnsatisfiable: DoNotSchedule
...
...
apiVersion : k8s.keycloak.org/v2alpha1
kind : Keycloak
metadata :
name : example- kc
spec :
scheduling :
priorityClassName : custom- high
affinity :
podAffinity :
preferredDuringSchedulingIgnoredDuringExecution :
- podAffinityTerm :
labelSelector :
matchLabels :
app : keycloak
app.kubernetes.io/managed-by : keycloak- operator
app.kubernetes.io/component : server
topologyKey : topology.kubernetes.io/zone
weight : 10
tolerations :
- key : "some-taint"
operator : "Exists"
effect : "NoSchedule"
topologySpreadConstraints :
- maxSkew : 1
topologyKey : kubernetes.io/hostname
whenUnsatisfiable : DoNotSchedule
...
...
Copy to Clipboard
Copied!
Toggle word wrap
Toggle overflow
有关调度概念的更多信息 ,请参阅 kubernetes 文档。
如果没有指定自定义关联性,您的 Pod 将具有同一区的关联性,以及同一节点的反关联性以提高可用性。如果可能有助于防止跨区缓存集群流量超过延迟,则调度到同一区。
要更改管理界面的端口,请在 Keycloak CR 中使用第一类色列字段 httpManagement.port
。要更改管理界面的属性,您可以通过提供 additionalOptions
字段来实现它。
您可以指定 port
和 additionalOptions
,如下所示:
apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
name: example-kc
spec:
httpManagement:
port: 9001
additionalOptions:
- name: http-management-relative-path
value: /management
apiVersion : k8s.keycloak.org/v2alpha1
kind : Keycloak
metadata :
name : example- kc
spec :
httpManagement :
port : 9001
additionalOptions :
- name : http- management- relative- path
value : /management
Copy to Clipboard
Copied!
Toggle word wrap
Toggle overflow
如果使用自定义镜像,Operator 会 不知道 在其中可能指定的任何配置选项。例如,它可能会导致管理界面使用 https
模式,但当自定义镜像中指定 TLS 设置时,Operator 会通过 http
访问它。为确保正确的 TLS 配置,请使用 Keycloak CR 中的 tlsSecret
和 truststores
字段,以便 Operator 可以反映这一点。
如果您需要提供可信证书,Keycloak CR 提供了顶级功能来配置服务器的信任存储,如 配置可信证书 中所述。
使用 Keycloak spec 的 truststores 小节来指定包含 PEM 编码文件的 Secret,或使用扩展名 .p12
或 .pfx
指定 PKCS12 文件,例如:
apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
name: example-kc
spec:
...
truststores:
my-truststore:
secret:
name: my-secret
apiVersion : k8s.keycloak.org/v2alpha1
kind : Keycloak
metadata :
name : example- kc
spec :
...
truststores :
my-truststore :
secret :
name : my- secret
Copy to Clipboard
Copied!
Toggle word wrap
Toggle overflow
其中 my-secret 的内容可以是 PEM 文件,例如:
apiVersion: v1
kind: Secret
metadata:
name: my-secret
stringData:
cert.pem: |
-----BEGIN CERTIFICATE-----
...
apiVersion : v1
kind : Secret
metadata :
name : my- secret
stringData :
cert.pem : |
-----BEGIN CERTIFICATE-----
...
Copy to Clipboard
Copied!
Toggle word wrap
Toggle overflow
在 Kubernetes 或 OpenShift 环境中,自动包含可信证书的已知位置。这包括 /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
和 /var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt
。
当您创建新实例时,Keycloak CR spec.bootstrapAdmin 小节可用于配置 bootstrap 用户和/或服务帐户。如果没有为 spec.bootstrapAdmin 指定任何内容,Operator 将创建一个名为 "metadata.name"-initial-admin 的 Secret,其带有用户名 temp-admin 和生成的密码。如果您为 bootstrap admin 用户指定 Secret 名称,则 Secret 将需要包含用户名和密码键值对。
如果您为 bootstrap admin 服务帐户指定 Secret 名称,则 Secret 将需要包含 client-id
和 client-secret
键值对。
如果已为集群创建了 master 域,则 spec.boostrapAdmin 会被有效地忽略。如果您需要创建恢复 admin 帐户,则需要直接在 Pod 上运行 CLI 命令。
有关如何引导临时 admin 用户或服务帐户并恢复丢失的 admin 访问权限的更多信息,请参阅 Admin bootstrap 和 recovery 指南。