此内容没有您所选择的语言版本。
Chapter 7. OpenShift Ansible Broker Configuration
7.1. Overview
When the OpenShift Ansible broker (OAB) is deployed in a cluster, its behavior is largely dictated by the broker’s configuration file loaded on startup. The broker’s configuration is stored as a ConfigMap object in the broker’s namespace (openshift-ansible-service-broker by default).
Example OpenShift Ansible Broker Configuration File
registry: 1 - type: dockerhub name: docker url: https://registry.hub.docker.com org: <dockerhub_org> fail_on_error: false - type: rhcc name: rhcc url: https://registry.access.redhat.com fail_on_error: true white_list: - "^foo.*-apb$" - ".*-apb$" black_list: - "bar.*-apb$" - "^my-apb$" - type: local_openshift name: lo namespaces: - openshift white_list: - ".*-apb$" dao: 2 etcd_host: localhost etcd_port: 2379 log: 3 logfile: /var/log/ansible-service-broker/asb.log stdout: true level: debug color: true openshift: 4 host: "" ca_file: "" bearer_token_file: "" image_pull_policy: IfNotPresent sandbox_role: "edit" keep_namespace: false keep_namespace_on_error: true broker: 5 bootstrap_on_startup: true dev_broker: true launch_apb_on_bind: false recovery: true output_request: true ssl_cert_key: /path/to/key ssl_cert: /path/to/cert refresh_interval: "600s" auth: - type: basic enabled: true secrets: 6 - title: Database credentials secret: db_creds apb_name: dh-rhscl-postgresql-apb
- 1
- See Registry Configuration for details.
- 2
- See DAO Configuration for details.
- 3
- See Log Configuration for details.
- 4
- See OpenShift Configuration for details.
- 5
- See Broker Configuration for details.
- 6
- See Secrets Configuration for details.
7.2. Modifying the OpenShift Ansible Broker Configuration
To modify the OAB’s default broker configuration after it has been deployed:
Edit the broker-config ConfigMap object in the OAB’s namespace as a user with cluster-admin privileges:
$ oc edit configmap broker-config -n openshift-ansible-service-broker
After saving any updates, redeploy the OAB’s deployment configuration for the changes to take effect:
$ oc rollout latest dc/asb -n openshift-ansible-service-broker
7.3. Registry Configuration
The registry
section allows you to define the registries that the broker should look at for APBs.
Field | Description | Required |
---|---|---|
| The name of the registry. Used by the broker to identify APBs from this registry. | Y |
|
The user name for authenticating to the registry. Not used when | N |
|
The password for authenticating to the registry. Not used when | N |
|
How the broker should read the registry credentials if they are not defined in the broker configuration via | N |
|
Name of the secret or file storing the registry credentials that should be read. Used when |
N, only required when |
| The namespace or organization that the image is contained in. | N |
|
The type of registry. Available adapters are | Y |
|
The list of namespaces to configure the | N |
|
The URL that is used to retrieve image information. Used extensively for RHCC while the | N |
| Should this registry fail, the bootstrap request if it fails. Will stop the execution of other registries loading. | N |
|
The list of regular expressions used to define which image names should be allowed through. Must have a white list to allow APBs to be added to the catalog. The most permissive regular expression that you can use is | N |
| The list of regular expressions used to define which images names should never be allowed through. See APB Filtering for more details. | N |
| The list of images to be used with an OpenShift Container Registry. | N |
7.3.1. Production or Development
A production broker configuration is designed to be pointed at a trusted container distribution registry, such as the Red Hat Container Catalog (RHCC):
registry: - name: rhcc type: rhcc url: https://registry.access.redhat.com tag: v3.9 white_list: - ".*-apb$" - type: local_openshift name: localregistry namespaces: - openshift white_list: []
However, a development broker configuration is primarily used by developers working on the broker. To enable developer settings, set the registry name to dev
and the dev_broker
field in the broker
section to true
:
registry: name: dev
broker: dev_broker: true
7.3.2. Storing Registry Credentials
The broker configuration determines how the broker should read any registry credentials. They can be read from the user
and pass
values in the registry
section, for example:
registry: - name: isv type: openshift url: https://registry.connect.redhat.com user: <user> pass: <password>
If you want to ensure these credentials are not publicly accessible, the auth_type
field in the registry
section can be set to the secret
or file
type. The secret
type configures a registry to use a secret from the broker’s namespace, while the file
type configures a registry to use a secret that has been mounted as a volume.
To use the secret
or file
type:
The associated secret should have the values
username
andpassword
defined. When using a secret, you must ensure that theopenshift-ansible-service-broker
namespace exists, as this is where the secret will be read from.For example, create a reg-creds.yaml file:
$ cat reg-creds.yaml --- username: <username> password: <password>
Create a secret from this file in the
openshift-ansible-service-broker
namespace:$ oc create secret generic \ registry-credentials-secret \ --from-file reg-creds.yaml \ -n openshift-ansible-service-broker
Choose whether you want to use the
secret
orfile
type:To use the
secret
type:In the broker configuration, set
auth_type
tosecret
andauth_name
to the name of the secret:registry: - name: isv type: openshift url: https://registry.connect.redhat.com auth_type: secret auth_name: registry-credentials-secret
Set the namespace where the secret is located:
openshift: namespace: openshift-ansible-service-broker
To use the
file
type:Edit the
asb
deployment configuration to mount your file into /tmp/registry-credentials/reg-creds.yaml:$ oc edit dc/asb -n openshift-ansible-service-broker
In the
containers.volumeMounts
section, add:volumeMounts: - mountPath: /tmp/registry-credentials name: reg-auth
In the
volumes
section, add:volumes: - name: reg-auth secret: defaultMode: 420 secretName: registry-credentials-secret
In the broker configuration, set
auth_type
tofile
andauth_type
to the location of the file:registry: - name: isv type: openshift url: https://registry.connect.redhat.com auth_type: file auth_name: /tmp/registry-credentials/reg-creds.yaml
7.3.3. Mock Registry
A mock registry is useful for reading local APB specs. Instead of going out to a registry to search for image specs, this uses a list of local specs. Set the name of the registry to mock
to use the mock registry.
registry: - name: mock type: mock
7.3.4. Dockerhub Registry
The dockerhub
type allows you to load APBs from a specific organization in the DockerHub. For example, the ansibleplaybookbundle organization.
registry: - name: dockerhub type: dockerhub org: ansibleplaybookbundle user: <user> pass: <password> white_list: - ".*-apb$"
7.3.5. APB Filtering
APBs can be filtered out by their image name using a combination of the white_list
or black_list
parameters, set on a registry basis inside the broker’s configuration.
Both are optional lists of regular expressions that will be run over the total set of discovered APBs for a given registry to determine matches.
Present | Allowed | Blocked |
---|---|---|
Only whitelist | Matches a regex in list. | Any APB that does not match. |
Only blacklist | All APBs that do not match. | APBs that match a regex in list. |
Both present | Matches regex in whitelist but not in blacklist. | APBs that match a regex in blacklist. |
None | No APBs from the registry. | All APBs from that registry. |
For example:
Whitelist Only
white_list: - "foo.*-apb$" - "^my-apb$"
Anything matching on foo.*-apb$
and only my-apb
will be allowed through in this case. All other APBs will be rejected.
Blacklist Only
black_list: - "bar.*-apb$" - "^foobar-apb$"
Anything matching on bar.*-apb$
and only foobar-apb
will be blocked in this case. All other APBs will be allowed through.
Whitelist and Blacklist
white_list: - "foo.*-apb$" - "^my-apb$" black_list: - "^foo-rootkit-apb$"
Here, foo-rootkit-apb
is specifically blocked by the blacklist despite its match in the whitelist because the whitelist match is overridden.
Otherwise, only those matching on foo.*-apb$
and my-apb
will be allowed through.
Example Broker Configuration registry
Section:
registry: - type: dockerhub name: dockerhub url: https://registry.hub.docker.com user: <user> pass: <password> org: <org> white_list: - "foo.*-apb$" - "^my-apb$" black_list: - "bar.*-apb$" - "^foobar-apb$"
7.3.6. Local OpenShift Container Registry
Using the local_openshift
type will allow you to load APBs from the OpenShift Container Registry that is internal to the OpenShift Container Platform cluster. You can configure the namespaces in which you want to look for published APBs.
registry: - type: local_openshift name: lo namespaces: - openshift white_list: - ".*-apb$"
7.3.7. Red Hat Container Catalog Registry
Using the rhcc
type will allow you to load APBs that are published to the Red Hat Container Catalog (RHCC) registry.
registry: - name: rhcc type: rhcc url: https://registry.access.redhat.com white_list: - ".*-apb$"
7.3.8. ISV Registry
Using the openshift
type allows you to load APBs that are published to the ISV container registry at registry.connect.redhat.com.
registry: - name: isv type: openshift user: <user> 1 pass: <password> url: https://registry.connect.redhat.com images: 2 - <image_1> - <image_2> white_list: - ".*-apb$"
- 1
- See Storing Registry Credentials for other authentication options.
- 2
- Because the
openshift
type currently cannot search the configured registry, it is required that you configure the broker with a list of images you would like to source from for when the broker bootstraps. The image names must be the fully qualified name without the registry URL.
7.3.9. Multiple Registries
You can use more than one registry to separate APBs into logical organizations and be able to manage them from the same broker. The registries must have a unique, non-empty name. If there is no unique name, the service broker will fail to start with an error message alerting you to the problem.
registry: - name: dockerhub type: dockerhub org: ansibleplaybookbundle user: <user> pass: <password> white_list: - ".*-apb$" - name: rhcc type: rhcc url: <rhcc_url> white_list: - ".*-apb$"
7.4. DAO Configuration
Field | Description | Required |
---|---|---|
| The URL of the etcd host. | Y |
|
The port to use when communicating with | Y |
7.5. Log Configuration
Field | Description | Required |
---|---|---|
| Where to write the broker’s logs. | Y |
| Write logs to stdout. | Y |
| Level of the log output. | Y |
| Color the logs. | Y |
7.6. OpenShift Configuration
Field | Description | Required |
---|---|---|
| OpenShift Container Platform host. | N |
| Location of the certificate authority file. | N |
| Location of bearer token to be used. | N |
| When to pull the image. | Y |
| The namespace that the broker has been deployed to. Important for things like passing parameter values via secret. | Y |
| Role to give to an APB sandbox environment. | Y |
| Always keep namespace after an APB execution. | N |
| Keep namespace after an APB execution has an error. | N |
7.7. Broker Configuration
The broker
section tells the broker what functionality should be enabled and disabled. It will also tell the broker where to find files on disk that will enable the full functionality.
Field | Description | Default Value | Required |
---|---|---|---|
| Allow development routes to be accessible. |
| N |
| Allow bind to be a no-op. |
| N |
| Allow the broker attempt to bootstrap itself on start up. Will retrieve the APBs from configured registries. |
| N |
| Allow the broker to attempt to recover itself by dealing with pending jobs noted in etcd. |
| N |
| Allow the broker to output the requests to the log file as they come in for easier debugging. |
| N |
| Tells the broker where to find the TLS key file. If not set, the API server will attempt to create one. |
| N |
| Tells the broker where to find the TLS .crt file. If not set, the API server will attempt to create one. |
| N |
| The interval to query registries for new image specs. |
| N |
| Allows the broker to escalate the permissions of a user while running the APB. |
| N |
| Sets the prefix for the URL that the broker is expecting. |
| N |
Async bind and unbind is an experimental feature and is not supported or enabled by default. With the absence of async bind, setting launch_apb_on_bind
to true
can cause the bind action to timeout and will span a retry. The broker will handle this with "409 Conflicts" because it is the same bind request with different parameters.
7.8. Secrets Configuration
The secrets
section creates associations between secrets in the broker’s namespace and APBs the broker runs. The broker uses these rules to mount secrets into running APBs, allowing the user to use secrets to pass parameters without exposing them to the catalog or users.
The section is a list where each entry has the following structure:
Field | Description | Required |
---|---|---|
| The title of the rule. This is just for display and output purposes. | Y |
|
The name of the APB to associate with the specified secret. This is the fully qualified name ( | Y |
| The name of the secret to pull parameters from. | Y |
You can download and use the create_broker_secret.py file to create and format this configuration section.
secrets: - title: Database credentials secret: db_creds apb_name: dh-rhscl-postgresql-apb
7.9. Running Behind a Proxy
When running the OAB inside of a proxied OpenShift Container Platform cluster, it is important to understand its core concepts and consider them within the context of a proxy used for external network access.
As an overview, the broker itself runs as a pod within the cluster. It has a requirement for external network access depending on how its registries have been configured.
7.9.1. Registry Adapter Whitelists
The broker’s configured registry adapters must be able to communicate with their external registries in order to bootstrap successfully and load remote APB manifests. These requests can be made via the proxy, however, the proxy must ensure that the required remote hosts are accessible.
Example required whitelisted hosts:
Registry Adapter Type | Whitelisted Hosts |
---|---|
|
|
|
|
7.9.2. Configuring the Broker Behind a Proxy Using Ansible
If during initial installation you configure your OpenShift Container Platform cluster to run behind a proxy (see Configuring Global Proxy Options), when the OAB is deployed it will:
- inherit those cluster-wide proxy settings automatically and
-
generate the required
NO_PROXY
list, including thecidr
fields andserviceNetworkCIDR
,
and no further configuration is needed.
7.9.3. Configuring the Broker Behind a Proxy Manually
If your cluster’s global proxy options were not configured during initial installation or prior to the broker being deployed, or if you have modified the global proxy settings, you must manually configure the broker for external access via proxy:
Before attempting to run the OAB behind a proxy, review Working with HTTP Proxies and ensure your cluster is configured accordingly to run behind a proxy.
In particular, the cluster must be configured to not proxy internal cluster requests. This is typically configured with a
NO_PROXY
setting of:.cluster.local,.svc,<serviceNetworkCIDR_value>,<master_IP>,<master_domain>,.default
in addition to any other desired
NO_PROXY
settings. See Configuring NO_PROXY for more details.NoteBrokers deploying unversioned, or v1 APBs must also add
172.30.0.1
to theirNO_PROXY
list. APBs prior to v2 extracted their credentials from running APB pods via anexec
HTTP request, rather than a secret exchange. Unless you are running a broker with experimental proxy support in a cluster prior to OpenShift Container Platform 3.9, you probably do not have to worry about this.Edit the broker’s
DeploymentConfig
as a user with cluster-admin privileges:$ oc edit dc/asb -n openshift-ansible-service-broker
Set the following environment variables:
-
HTTP_PROXY
-
HTTPS_PROXY
-
NO_PROXY
NoteSee Setting Proxy Environment Variables in Pods for more information.
-
After saving any updates, redeploy the OAB’s deployment configuration for the changes to take effect:
$ oc rollout latest dc/asb -n openshift-ansible-service-broker
7.9.4. Setting Proxy Environment Variables in Pods
It is common that APB pods themselves may require external access via proxy as well. If the broker recognizes it has a proxy configuration, it will transparently apply these environment variables to the APB pods that it spawns. As long as the modules used within the APB respect proxy configuration via environment variable, the APB will also use these settings to perform its work.
Finally, it is possible the services spawned by the APB may also require external network access via proxy. The APB must be authored to set these environment variables explicitly if recognizes them in its own execution environment, or the cluster operator must manually modify the required services to inject them into their environments.