Advanced configuration

Advanced configuration settings for Continuous Delivery for PE help you fine-tune aspects of the software that can impact runtime and operation speed.

Configuration reference

The following settings are configurable via Hiera. These values can be found in data/common.yaml in the cd4peadm module.

To update Continuous Delivery for Puppet Enterprise with new configuration values, make edits to data/common.yaml and run the cd4peadm::configure plan.

targets: A map containing three keys, one for each Continuous Delivery for PE component: backend, database, and ui. Each value is an array of the targets on which to install each of the components.
Note: We only support an all-in-one install, so all components must be installed on the same single target. When running the cd4peadm::install plan, these are populated with the selected target from the inventory.
admin_db_password: The overarching root password for managing a Postgres database. Can be automatically configured by the bootstrap plan.
cd4pe_db_username: The username for the database that stores the main app data. Defaults to cd4pe
cd4pe_db_password: The password for the database that stores the main app data.
query_db_username: The username for the database that stores data for the Nodes page. Defaults to query.
query_db_password: The password for the database that stores data for the Nodes page.
root_username: The username for the root Continuous Delivery for PE account. Defaults to admin
root_password: The password to the root Continuous Delivery for PE account.
runtime: The container runtime to use on the target host. Can be docker or podman. Defaults to docker
secret_key: The key used to encrypt secret data in the database. Automatically generated.
backup_dir: The directory where backups are stored. Defaults to /var/lib/puppetlabs/cd4pe/backups.
containers: A map containing four keys, one for each of the component containers:
- pipelinesinfra: The container for the backend application. Has the following options:
  - log_level: Configures backend logging. Value can be info, debug, or trace. Defaults to info
  - max_log_size_mb: The size a log file can grow to before rotation, in megabytes. Defaults to 200MB.
  - keep_log_files: The number of past log files to keep after rotation. Defaults to 5.
- teams_ui: The container for the web UI. Has the following options:
  - max_log_size_mb: The size a log file can grow to before rotation, in megabytes. Defaults to 100MB.
  - keep_log_files: The number of past log files to keep after rotation. Defaults to 3.
- postgres: The container for the database. Has the following options:
  - log_level: Configures database logging. Value can be INFO, NOTICE, WARNING, or ERROR. Defaults to ERROR
  - max_log_size_mb: The size a log file can grow to before rotation, in megabytes. Defaults to 100MB.
  - keep_log_files: The number of past log files to keep after rotation. Defaults to 3.
- query: The container for the query service, which backs the Nodes page. Has the following options:
  - log_level: Configures query service logging. Value can be INFO, DEBUG, or TRACE. Defaults to DEBUG
  - max_log_size_mb: The size a log file can grow to before rotation, in megabytes. Defaults to 100MB.
  - keep_log_files: The number of past log files to keep after rotation. Defaults to 3.
java_args: Arguments to pass to the JVM that runs Continuous Delivery for PE's backend. Defaults to -Xmx1024M -Xms1024M
job_http_read_timeout_mins: The timeout for web requests made from jobs. Defaults to 29 minutes.
job_global_timeout_mins: The overall timeout for a running job. Defaults to 30 minutes.
bolt_pcp_timeout_secs: The timeout for Bolt's PCP transport. Used during jobs to contact the PE Orchestrator. Defaults to 60 seconds.
http_connection_timeout_secs: The connection timeout for external HTTP requests. Defaults to 120 seconds.
http_read_timeout_secs: The read timeout for external HTTP requests. Defaults to 120 seconds.
http_write_timeout_secs: The write timeout for external HTTP requests. Defaults to 120 seconds.
http_request_timeout_secs: The total amount of time an external HTTP request stays open. Defaults to 300 seconds.
puppetdb_connection_timeout_secs: The total amount of time a connection to PuppetDB stays open. Defaults to the value of http_connection_timeout_secs
repo_caching: Whether to enable Git repository caching, which can improve job performance if the repos are large. Defaults to false.
repo_cache_retrieval_timeout_mins: The timeout for a thread waiting to access a cached repo. Only used when repo caching is enabled. Defaults to 28 minutes.
max_login_attempts: The max number of login attempts before locking out a user. Defaults to 10.
failed_login_attempt_period_mins: The amount of time to watch for failed login attempts by a user. Defaults to 15 minutes.
lockout_period_mins: The amount of time to lock out a user from attempting to log in. Defaults to 120 minutes.
query_complexity_limit: Controls compound filtering in the query service, sometimes tuned for performance reasons. Defaults to 100.
ssl_cert_chain: User-provided certificate chain including a CA and leaf certificates for the Continuous Delivery for PE host.
ssl_crl: The CRL that the provided CA is associated with.
ssl_private_key: The private key used to sign the provided certificate chain.

Improve job performance by caching Git repositories

If you have large Git repositories, you can enable Git repository caching to improve job performance. By default, repository caching is disabled.

The cached repository's files and data are stored on the container running Continuous Delivery for PE at /<DEFAULT_ROOT_STORAGE_DIRECTORY>/repos. The entire repository is cloned from source control, including branches; therefore, caching requires space equivalent to the size of the uncompressed repository.

Cached repositories are not automatically deleted. When attempting to read from the cached repository, if the cached version is missing object ID references, or if the previous cache attempt failed, then the cached version is deleted and re-cloned.

Enable repository caching, as outlined in the Configuration reference, using:

 repo_caching: true

Including the `.git` directory in cached repositories

The .git directory is automatically omitted when copying cached Git repositories to job hardware. This means that the job cannot perform Git actions on the code. If needed, you can adjust this setting so that the .git directory is included in the cached repository.

Include the .git directory in copies of cached Git repositories sent to job hardware, as outlined in the Configuration reference, using:

include_git_history_for_jobs: true

Use custom TLS certificates

By default, Continuous Delivery for Puppet Enterprise (PE) uses automatically generated certificates. Your organization's security policies might require using custom certificates or adding additional certificates. Use these steps to configure custom TLS certificates for the Continuous Delivery for PE web UI connection.

Before you begin

It is recommended to do this after you Install Continuous Delivery for PE, but you could do this during initial setup.

Obtain a custom certificate and accompanying key pair. You need the entire certificate, including the header and footer, and the private key. Most configurations also need a CA certificate chain.
Make sure you have configured the DNS names you want to use for Continuous Delivery for PE. When you generate and sign the CSR, make sure it includes subject alternative names for all DNS names used to connect to the Continuous Delivery for PE host.
Edit the Hiera section in the data/common.yaml file.
Combine your certificate and CA to create a cert chain and add this to Hiera for the ssl_cert_chain key.
Add your CRL that the provided CA is associated with in the ssl_crl setting in Hiera.
Encrypt your private key and place the resulting encrypted string in the ssl_private_key setting in Hiera:
```
bolt secret encrypt <private key>
```
Update the configuration with the Hiera changes:
```
bolt plan run cd4peadm::configure
```
Optional: Use OpenSSL or curl commands to verify your certificates.

What to do next

If you want to go back to using the automatically generated certificates, remove the above keys from Hiera and re-run the configure plan.

To use a custom certificate for your Continuous Delivery for PE SAML SSO configuration, refer to Configure SAML.

Enable compiler maintenance mode

You can tell Continuous Delivery for Puppet Enterprise (PE) to skip offline or unavailable compilers and replicas when deploying code.

CAUTION: With this setting enabled, Code Manager deployments are reported as successful as long as the code was deployed to the primary server. Continuous Delivery for PE does not tell you if it skipped a compiler or replica. You are only notified if the deployment to the primary server failed.

You must manually monitor the status of your compilers and replicas to ensure they're in sync with the primary server. If a compiler or replica is out of sync, you'll need to manually deploy code to that compiler or replica.

To enable this setting:

In the Continuous Delivery for PE web UI, navigate to Settings > Puppet Enterprise.
Locate the PE instance you want to configure and click More actions > Edit integration.
In the Compiler maintenance mode section, enable Ignore unavailable compilers or replicas when deploying code.
Click Save changes.

Important: This setting allows your pipelines to continue while compilers are undergoing maintenance or experiencing transient issues. When enabled, Code Manager deployments report as successful as long as the code was deployed to the primary server. Therefore, you must manually track that the code on your compilers and replicas is in sync.

Use the Code Manager API GET /v1/deploys/status endpoint to make sure your compilers and replicas are in sync with the primary server. The file-sync-client-status portion of the response contains all servers with code synced. In the deployed array for each server, compare the deploy-signature and date for each deployment. The deploy-signature is the hash of the git commit that was last synced to the server. If a compiler or replica has a different hash that the primary, you must Deploy code manually to the desynchronized compiler or replica.