diff --git a/README.md b/README.md index 7d2e565e..e992c3ce 100644 --- a/README.md +++ b/README.md @@ -140,6 +140,11 @@ These are user defined, and should be present prior to the deployment of the Hea To undeploy the operator, simply set the `enabled` value to false from within the `OpenStackControlPlane` resource. +### Customize httpd + +- [Customize httpd](config/samples/httpd-overrides): inject custom httpd + configuration through extraMounts interface + ## Contributing The following guide relies on a already deployed `OpenStackControlPlane`. If you don't already have this, you can diff --git a/config/samples/httpd-overrides/README.md b/config/samples/httpd-overrides/README.md new file mode 100644 index 00000000..bfc2844c --- /dev/null +++ b/config/samples/httpd-overrides/README.md @@ -0,0 +1,137 @@ +# Heat HTTPD Configuration Overrides + +The heat-operator provides mechanisms to customize the Apache HTTPD server +configuration through the use of custom configuration files. This feature +leverages the +[ExtraMounts](https://github.com/openstack-k8s-operators/dev-docs/blob/main/extra_mounts.md) +functionality to mount custom HTTPD configuration files into the Heat +deployment. + +## How It Works + +1. **Custom Configuration Files**: Create HTTPD configuration files with your + custom settings +2. **ConfigMap**: Create ConfigMaps from files containing the overrides +3. **OpenStackControlPlane Patch**: Patch the control plane to mount the + generated ConfigMap into Heat containers. The HTTPD configuration + automatically includes files mounted to `/etc/httpd/conf_custom/*.conf` + + +### Step 1: Create Custom HTTPD Configuration + +Create your custom HTTPD configuration file(s). As a best practice the filename +could start with the `httpd_custom_` prefix, but all `*.conf` files mounted to +`/etc/httpd/conf_custom/` are automatically included by the `IncludeOptional` +directive in the base `httpd` configuration. + +Example (`httpd_custom_timeout.conf`): +```apache +# Custom timeout settings for Heat +Timeout 300 +KeepAliveTimeout 15 +``` + +### Step 2. Create a ConfigMap + +Create a Kubernetes `ConfigMap` containing your custom configuration files: + +```bash +oc create configmap httpd-overrides --from-file=httpd_custom_timeout.conf +``` + +It is possible to add multiple configuration files containing dedicated +configuration directives: + +```bash +oc create configmap httpd-overrides \ + --from-file=httpd_custom_timeout.conf \ + --from-file=httpd_custom_security.conf \ + --from-file=httpd_custom_logging.conf +``` + +The following example is based on a single customization file and demonstrates +how to set custom `Timeout` and `KeepAliveTimeout` parameters. + +### Step 3: Configure ExtraMounts in the OpenStackControlPlane + +Update your `OpenStackControlPlane` resource to include the custom HTTPD +configuration files using `extraMounts`. The simplest approach is to mount +the entire ConfigMap to the target `/etc/httpd/conf_custom` mount point. + +Heat exposes two API services (`heatAPI` and `heatCfnAPI`), each with its +own HTTPD vhost. You can apply overrides to either or both: + +```yaml +apiVersion: core.openstack.org/v1beta1 +kind: OpenStackControlPlane +metadata: + name: openstack +spec: + heat: + template: + heatAPI: + extraMounts: + - extraVol: + - extraVolType: httpd-overrides + mounts: + - mountPath: /etc/httpd/conf_custom + name: httpd-overrides + readOnly: true + volumes: + - configMap: + name: httpd-overrides + name: httpd-overrides + heatCfnAPI: + extraMounts: + - extraVol: + - extraVolType: httpd-overrides + mounts: + - mountPath: /etc/httpd/conf_custom + name: httpd-overrides + readOnly: true + volumes: + - configMap: + name: httpd-overrides + name: httpd-overrides +``` + +## Common Use Cases + +- **Timeout Adjustments**: Modify request timeout values for specific environments +- **Security Headers**: Add custom security headers or configurations +- **Logging**: Customize Apache logging configuration +- **Performance Tuning**: Adjust worker processes, connection limits, etc. + +## Verification + +After deploying your custom `HTTPD` configuration, you can verify that the +settings have been properly applied: + +### 1. Find the Heat Pod + +First, identify the running Heat pod: + +```bash +$ oc get pods -l service=heat +``` + +### 2. Verify Configuration Loading + +Connect to the Heat Pod and check that your custom configuration has been +loaded: + +```bash +# Replace with the actual pod name from step 1 +oc rsh -c heat-api-httpd +# Inside the pod, dump the HTTPD configuration and check for your custom settings +httpd -D DUMP_CONFIG +``` + +### 3. Additional Verification Commands + +You can also verify other aspects of the configuration: + +```bash +# Check all loaded configuration files +$ httpd -D DUMP_INCLUDES +``` diff --git a/config/samples/httpd-overrides/httpd_custom_timeout.conf b/config/samples/httpd-overrides/httpd_custom_timeout.conf new file mode 100644 index 00000000..94573158 --- /dev/null +++ b/config/samples/httpd-overrides/httpd_custom_timeout.conf @@ -0,0 +1,5 @@ +# Custom timeout settings for Heat HTTPD +# This file demonstrates how to override default timeout values +# for Apache HTTPD serving Heat API requests +Timeout 300 +KeepAliveTimeout 15 diff --git a/config/samples/httpd-overrides/httpd_overrides.yaml b/config/samples/httpd-overrides/httpd_overrides.yaml new file mode 100644 index 00000000..c9c6b4c9 --- /dev/null +++ b/config/samples/httpd-overrides/httpd_overrides.yaml @@ -0,0 +1,31 @@ +apiVersion: core.openstack.org/v1beta1 +kind: OpenStackControlPlane +metadata: + name: openstack +spec: + heat: + template: + heatAPI: + extraMounts: + - extraVol: + - extraVolType: httpd-overrides + mounts: + - mountPath: /etc/httpd/conf_custom + name: httpd-overrides + readOnly: true + volumes: + - configMap: + name: httpd-overrides + name: httpd-overrides + heatCfnAPI: + extraMounts: + - extraVol: + - extraVolType: httpd-overrides + mounts: + - mountPath: /etc/httpd/conf_custom + name: httpd-overrides + readOnly: true + volumes: + - configMap: + name: httpd-overrides + name: httpd-overrides diff --git a/config/samples/httpd-overrides/kustomization.yaml b/config/samples/httpd-overrides/kustomization.yaml new file mode 100644 index 00000000..169c8b69 --- /dev/null +++ b/config/samples/httpd-overrides/kustomization.yaml @@ -0,0 +1,20 @@ +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +resources: + - https://raw.githubusercontent.com/openstack-k8s-operators/openstack-operator/main/config/samples/core_v1beta1_openstackcontrolplane_galera_network_isolation.yaml + +patches: + - target: + kind: OpenStackControlPlane + name: .* + patch: |- + - op: replace + path: /metadata/name + value: openstack + - path: httpd_overrides.yaml + +configMapGenerator: +- files: + - ./httpd_custom_timeout.conf + name: httpd-overrides diff --git a/templates/heat/config/heat-api-httpd.conf b/templates/heat/config/heat-api-httpd.conf index 2e2c7f35..5fa53d1c 100644 --- a/templates/heat/config/heat-api-httpd.conf +++ b/templates/heat/config/heat-api-httpd.conf @@ -54,5 +54,8 @@ ErrorLog /dev/stdout WSGIPassAuthorization On Timeout {{ $.Timeout }} + + IncludeOptional conf_custom/*.conf + {{ end }} diff --git a/templates/heat/config/heat-cfnapi-httpd.conf b/templates/heat/config/heat-cfnapi-httpd.conf index cb696511..1885d3cb 100644 --- a/templates/heat/config/heat-cfnapi-httpd.conf +++ b/templates/heat/config/heat-cfnapi-httpd.conf @@ -54,5 +54,8 @@ ErrorLog /dev/stdout WSGIPassAuthorization On Timeout {{ $.Timeout }} + + IncludeOptional conf_custom/*.conf + {{ end }}