Change and apply configuration

Change a setting in the source that owns it, follow its apply mode, then verify the effective behavior.

Know the owner

  • Edit UI-created routes, policies, and saved settings in the UI.
  • Edit discovered services and their inline policies in Docker labels.
  • A source badge or locked field identifies a setting controlled outside the UI.
  • Do not recreate a label-owned resource in the UI to work around ownership.

UI

Save the change, read any validation result, and check its apply badge. If the change is staged and automatic apply is off, open Services, select the relevant service, and choose Apply.

Cloud integration, error reporting, and installation ID

Open Settings → Cloud to review the installation ID and connection status. Cloud integration is the master switch and defaults to off. Enabling it permits automatic enrollment and reveals Health reporting, Error reporting, WAF ruleset updates, and Cloud Protection. Each optional feature has its own choice; connecting does not enable health or error reporting. Cloud Protection is coming later for Community, Business and Enterprise and cannot yet be enabled.

Cloud records the public IP address that each signed installation request arrives from, whatever the Telemetry choice. It keeps only the latest address and clears it 30 days after it was last seen. Behind NAT, that address belongs to your network rather than this host. Clearplane operators can see it, and so can the members of an organization the installation is linked to.

While Cloud integration is on, Core sends a signed presence heartbeat about every 30 seconds. It contains the installation ID through the credential and the running Clearplane release; Cloud records its own receipt time. This small operational heartbeat is independent of Health reporting, so turning optional health off does not make a running gateway appear offline.

Health reporting is off by default. When enabled locally and accepted by the linked organization, the gateway sends one attributable sample about every 30 seconds. Host fields are uptime, CPU, used/total memory and used/total space on the configured data volume. Core, Edge, UI and Container proxy each report availability, uptime, CPU and used/total memory. Clearplane does not send hostnames, local addresses, paths, process lists, arbitrary containers, routes, request or response data, traffic counts, WAF detections, credentials or free text. Cloud keeps Community and unlinked health for 7 days, Business for 30 days and Enterprise for 90 days. Health reporting does not create alerts.

Turning Health reporting off stops new local collection and upload but keeps retained Cloud data until its plan retention deadline. Its confirmation offers Also clear retained Cloud health data, unchecked by default. Clear health data is also available as a separate destructive action in Settings. A clear request is saved locally before Cloud is contacted and is retried after failures or restarts until acknowledged, even if the same settings save turned Cloud integration off. An organization owner can independently stop or resume Cloud ingestion and clear retained data from the installation page.

Error reporting sends diagnostic metadata from the Core, Edge, UI host and ContainerProxy server processes. Each report contains an event UUID, time, component, release, exception type, SHA-256 message-template hash and up to 16 type/method names. It excludes message text, exception messages, file paths, request properties, credentials and raw logs. Reports are associated with a persistent instance identity and are pseudonymous, not anonymous.

Core collects only events that occurred after the current error-reporting opt-in. Local diagnostic metadata remains in ordinary local logs under the configured log-retention policy.

Turning Error reporting off and saving discards its pending queue and prevents further uploads. Turning Cloud integration off also clears feature selections and stops Cloud connections. Already accepted Cloud reports follow the 30-day retention policy. A stale settings form is rejected; no Edge apply or restart is needed.

WAF ruleset updates is off by default. Cloud ruleset updates describes checks, verification and activation. The manifest request sends the running Clearplane version, even when Telemetry is off. No traffic, route or detection data is sent. Default update strategy decides what a new release does: Manual only installs it, Detection (the default) activates it in Detection, and Prevention activates it in Prevention. Under Prevention, a ruleset that Cloud adds later blocks immediately. Turning Cloud integration off also turns updates off; installed rulesets stay active.

The Installation ID is a random UUID generated once per installation database. It stays unchanged across restarts, upgrades and consent changes. Settings readers can view and copy it; the API cannot change it. Its value grants no authority. Enabling Cloud creates an ECDSA P-256 private key under Core's persistent data directory at secrets/cloud/<installation-id>.key. Back up the database and keys together. A previously connected installation with a missing or invalid key fails closed; contact the Cloud operator for credential rotation rather than deleting the identity. Copying a database and key copies that identity and must not be used to provision independent installations.

Core uses https://cloud.clearplane.net/api/ for enrollment, token exchange, signed uploads and ruleset downloads. Access tokens carry installation:read installation:claim errors:write rulesets:read telemetry:write; release downloads stay under that HTTPS base and do not follow redirects. No internal mTLS client certificates are sent to Cloud. Enrollment stores the installation ID and public key; a hash of the observed IPv4 /24 or IPv6 /64 network is retained for 24 hours to enforce a five-new-instances-per-network quota. Contact the Cloud operator if this enrollment limit prevents connecting a fleet. Cloud outages leave local protection available.

Cloud serves Community rulesets to enrolled installations without a customer account. Cloud stores the last successful manifest request time and the latest downloaded version and download time for each ruleset, associated with the installation ID. A download does not establish that the release was activated. These records remain with the installation; its deletion removes them. Cloud does not store the Clearplane version sent in the manifest query or any traffic, route or detection content from update requests.

The operator API exposes GET /api/privacy-configuration with Settings.Read and PUT /api/privacy-configuration with Settings.Write, through the authenticated Edge boundary. Submit the returned updatedAt, feature flags and update strategy when saving. The PUT changes preferences only and never infers data deletion. DELETE /api/cloud/telemetry with Settings.Write explicitly requests clearing and returns the refreshed state. Identity, Cloud acceptance and connection status are read-only.

Enrollment works without a Cloud account. To view this gateway in your organization's Cloud workspace:

  1. In the gateway's Settings → Cloud, enable and save Cloud integration, wait for a connection and copy the installation ID.
  2. Sign in to Clearplane Cloud as an organization owner. Open Installations → Connect an installation, paste the installation ID and create a claim code.
  3. Paste that code into Claim code under Organization in the gateway's Cloud settings. Select Link, verify the organization name and select Confirm organization. This requires local settings write permission. Once linked, the gateway shows the organization there instead of the claim code.
  4. Return to Cloud's Installations page. Organization members can view linked installations, retained health samples and WAF delivery details. Customer error-report browsing remains in development.

To unlink from the gateway, open Settings → Cloud → Organization and select Unlink. This requires local settings write permission. An organization owner can instead open the installation in Cloud and select Remove installation. Organization members lose access as soon as it is unlinked. The installation keeps its Cloud identity and can be linked again with a new claim code.

A claim code expires after ten minutes and applies only to the specified installation and organization. Creating another code replaces the organization's previous one. The gateway signs the request with its existing private key; never paste that key into Cloud. If confirmation is interrupted, retry the same code or check the Cloud installation list before generating another.

Linking preserves the installation identity, credentials and existing history. It does not change reporting choices or enable remote management. Turning Cloud off stops further gateway requests; it does not remove the organization link or erase previously accepted data. Ownership transfer and deletion are not available yet.

Local operator endpoints are POST /api/cloud/claim/preview and POST /api/cloud/claim; both require Settings.Write, a completed installation, a prior Cloud connection and currently enabled Cloud integration. The confirmation includes the organization ID returned by the preview.

Docker labels

Change the application or Clearplane-container label at its source. Wait for discovery or settings reconciliation, then check the UI for the effective value and source. For discovered routes, the automatic-apply setting controls whether a valid change is published immediately.

Use the configuration catalog to check whether a setting is Immediate, Validated, Apply required, or Restart required.

Verify

Confirm the effective value and source in the UI. Then test the behavior the setting controls; a successful save alone does not prove that staged or restart-required work is active.