PipeCD – Managing Control Plane

Docs-V0.57.x: Architecture overview

Mon, 01 Jan 0001 00:00:00 +0000

Component Architecture

The control plane is a centralized part of PipeCD. It contains several services as below to manage the application, deployment data and handle all requests from pipeds and web clients:

Server

server handles all incoming gRPC requests from pipeds, web clients, incoming HTTP requests such as auth callback from third party services. It also serves all web assets including HTML, JS, CSS… This service can be easily scaled by updating the pod number.

Cache

cache is a single pod service for caching internal data used by server service. Currently, this cache service is powered by redis. You can configure the control plane to use a fully-managed redis cache service instead of launching a cache pod in your cluster.

Ops

ops is a single pod service for operating PipeCD owner’s tasks. For example, it provides an internal web page for adding and managing projects; it periodically removes the old data; it collects and saves the deployment insights.

Data Store

Data store is a storage for storing model data such as applications and deployments. This can be a fully-managed service such as GCP Firestore, GCP Cloud SQL or AWS RDS (currently we choose MySQL v8 as supported relational data store). You can also configure the control plane to use a self-managed MySQL server. When installing the control plane, you have to choose one of the provided data store services.

File Store

File store is a storage for storing stage logs, application live states. This can be a fully-managed service such as GCP GCS, AWS S3, or a self-managed service such as Minio. When installing the control plane, you have to choose one of the provided file store services.

Docs-V0.57.x: Adding a project

Mon, 01 Jan 0001 00:00:00 +0000

The control plane ops can add a new project for a team. Project adding can be simply done from an internal web page prepared for the ops. Because that web service is running in an ops pod, in order to access it, use the kubectl port-forward command to forward a local port to a port on the ops pod as follows:

kubectl port-forward service/pipecd-ops 9082 --namespace={NAMESPACE}

Then, access to http://localhost:9082.

On that page, you will see the list of registered projects and a link to register new projects. Registering a new project requires only a unique ID string and an optional description text.

Once a new project has been registered, a static admin (username, password) will be automatically generated for the project admin. You can send that information to the project admin. The project admin first uses the provided static admin information to log in to PipeCD. After that, they can change the static admin information, configure the SSO, RBAC or disable static admin user.

Caution: The Role-Based Access Control (RBAC) setting is required to enable your team to log in using SSO. Please make sure you have that set up before disabling the static admin user.

Docs-V0.57.x: Authentication and authorization

Mon, 01 Jan 0001 00:00:00 +0000

Static Admin

When the PipeCD owner adds a new project, an admin account will be automatically generated for the project. After that, PipeCD owner sends that static admin information including username, password strings to the project admin, who can use that information to log in to PipeCD web with the admin role.

After logging, the project admin should change the provided username and password. Or disable the static admin account after configuring the single sign-on for the project.

Single Sign-On (SSO)

Single sign-on (SSO) allows users to log in to PipeCD by relying on a trusted third-party service.

The project can be configured to use a shared SSO configuration (shared OAuth application) instead of needing a new one. In that case, while creating the project, the PipeCD owner specifies the name of the shared SSO configuration should be used, and then the project admin can skip configuring SSO at the settings page.

Supported service

GitHub
Generic OIDC

Note: In the future, we want to support such as Google Gmail, Bitbucket…

Github

Before configuring the SSO, you need an OAuth application of the using service. For example, GitHub SSO requires creating a GitHub OAuth application as described in this page:

https://docs.github.com/en/developers/apps/creating-an-oauth-app

The authorization callback URL should be https://YOUR_PIPECD_ADDRESS/auth/callback.

Generic OIDC

PipeCD supports any OIDC provider, with tested providers including Keycloak, Auth0, and AWS Cognito. The only supported authentication flow currently is the Authorization Code Grant.

Requirements and Troubleshooting:

The OIDC provider must provide claims for user’s roles and username.
Roles claim value must use the same values as pre-configured project RBAC Roles.
Claims can be retrieved from the IdToken or UserInfo endpoint. The UserInfo endpoint will be used if the issuer supports it.
You can use set a custom claim key name for roles and username in the OIDC provider. Using usernameClaimKey and rolesClaimKey in the configuration. If not set, the default value will be chosen in the following order:
- Supported Claims Key for Username (in order of priority): username, preferred_username,name, cognito:username
- Supported Claims Key for Role (in order of priority): groups, roles, cognito:groups, custom:roles, custom:groups
If no usable claims are found, Unable to find user error will be shown.
If no roles are found, user can not access any resources. (If allowStrayAsViewer is set to true, user can access as a viewer)

Provider Configuration Examples:

Keycloak

Client authentication: On
Valid redirect URIs: https://YOUR_PIPECD_ADDRESS/auth/callback
Client scopes: Add a new mapper to the <client-id>-dedicated scope. For instance, map Group Membership information to the groups claim (Full group path should be off).

Control Plane configuration:

apiVersion: "pipecd.dev/v1beta1"
kind: ControlPlane
spec:
  sharedSSOConfigs:
    - name: oidc
      provider: OIDC
      oidc:
        clientId: <CLIENT_ID>
        clientSecret: <CLIENT_SECRET>
        issuer: https://<KEYCLOAK_ADDRESS>/realms/<REALM>
        redirectUri: https://<PIPECD_ADDRESS>/auth/callback
        scopes:
          - openid
          - profile

Okta

Allowed Callback URLs: https://YOUR_PIPECD_ADDRESS/auth/callback

Control Plane configuration:

apiVersion: "pipecd.dev/v1beta1"
kind: ControlPlane
spec:
  sharedSSOConfigs:
    - name: oidc
      provider: OIDC
      oidc:
        clientId: <CLIENT_ID>
        clientSecret: <CLIENT_SECRET>
        issuer: https://<OKTA_ID>.okta.com
        redirectUri: https://<PIPECD_ADDRESS>/auth/callback
        scopes:
          - openid
          - profile
          - groups

Auth0

Allowed Callback URLs: https://YOUR_PIPECD_ADDRESS/auth/callback

Control Plane configuration:

apiVersion: "pipecd.dev/v1beta1"
kind: ControlPlane
spec:
  sharedSSOConfigs:
    - name: oidc
      provider: OIDC
      oidc:
        clientId: <CLIENT_ID>
        clientSecret: <CLIENT_SECRET>
        issuer: https://<AUTH0_ADDRESS>
        redirectUri: https://<PIPECD_ADDRESS>/auth/callback
        scopes:
          - openid
          - profile

Roles/Groups Claims For Role or Groups information mapping using Auth0 Actions, here is an example for setting custom:roles:

exports.onExecutePostLogin = async (event, api) => {
  let namespace = "custom";
  if (namespace && !namespace.endsWith("/")) {
    namespace += ":";
  }
  api.idToken.setCustomClaim(namespace + "roles", event.authorization.roles);
};

AWS Cognito

Allowed Callback URLs: https://YOUR_PIPECD_ADDRESS/auth/callback

Control Plane configuration:

apiVersion: "pipecd.dev/v1beta1"
kind: ControlPlane
spec:
  sharedSSOConfigs:
    - name: oidc
      provider: OIDC
      oidc:
        clientId: <CLIENT_ID>
        clientSecret: <CLIENT_SECRET>
        issuer: https://cognito-idp.<AWS_REGION>.amazonaws.com/<USER_POOL_ID>
        redirectUri: https://<PIPECD_ADDRESS>/auth/callback
        scopes:
          - openid
          - profile

Custom Claims Key

In some cases, the OIDC provider may not provide the claims with the default key names like groups. You can set the custom claim key name for roles and username in the control plane configuration to map the claims from the OIDC provider. To be cautious, OIDC providers can not be used if issuer discovery is not supported.

apiVersion: "pipecd.dev/v1beta1"
kind: ControlPlane
spec:
  sharedSSOConfigs:
    - name: oidc
      provider: OIDC
      oidc:
        clientId: <CLIENT_ID>
        clientSecret: <CLIENT_SECRET>
        issuer: https://<OIDC_ADDRESS>
        redirectUri: https://<PIPECD_ADDRESS>/auth/callback
        scopes:
          - openid
          - profile
        usernameClaimKey: username # change to your custom claim key
        rolesClaimKey: roles # change to your custom claim key
        avatarUrlClaimKey: picture # change to your custom claim key

(Optional) You can choose to use the avatar URL from the OIDC provider. Using avatarUrlClaimKey in the configuration. If not set, the default value will be chosen in the following order: picture, avatar_url

Custom OIDC Configuration

If you want to set your custom endpoint without using the endpoint from the issuer, you can set the authorization_endpoint, token_endpoint, userinfo_endpoint in the control plane configuration.

apiVersion: "pipecd.dev/v1beta1"
kind: ControlPlane
spec:
  sharedSSOConfigs:
    - name: oidc
      provider: OIDC
      oidc:
        clientId: <CLIENT_ID>
        clientSecret: <CLIENT_SECRET>
        issuer: https://<OIDC_ADDRESS>
        redirectUri: https://<PIPECD_ADDRESS>/auth/callback
        scopes:
          - openid
          - profile
        authorization_endpoint: https://<OIDC_ADDRESS>/authorize # change to your custom endpoint
        token_endpoint: https://<OIDC_ADDRESS>/token # change to your custom endpoint
        userinfo_endpoint: https://<OIDC_ADDRESS>/userinfo # change to your custom endpoint

Role-Based Access Control (RBAC)

Role-based access control (RBAC) allows restricting access on the PipeCD web-based on the roles of user groups within the project. Before using this feature, the SSO must be configured.

PipeCD provides three built-in roles:

Viewer: has only permissions to view existing resources or data.
Editor: has all viewer permissions, plus permissions for actions that modify state, such as manually syncing application, canceling deployment…
Admin: has all editor permissions, plus permissions for updating project configurations.

Configuring the PipeCD’s roles

The below table represents PipeCD’s resources with actions on those resources.

resource	get	list	create	update	delete
application	○	○	○	○	○
deployment	○	○		○
event		○
piped	○	○	○	○
project	○			○
apiKey		○	○	○
insight	○

Each role is defined as a combination of multiple policies under this format.

resources=RESOURCE_NAMES;actions=ACTION_NAMES

The * represents all resources and all actions for a resource.

resources=*;actions=ACTION_NAMES
resources=RESOURCE_NAMES;actions=*
resources=*;actions=*

Configuring the PipeCD’s user groups

User Group represents a relation with a specific team (GitHub)/group (Google) and an arbitrary role. All users belong to a team/group will have all permissions of that team/group.

In case of using the GitHub team as a PipeCD user group, the PipeCD user group must be set in lowercase. For example, if your GitHub team is named ORG/ABC-TEAM, the PipeCD user group would be set as ORG/abc-team. (It’s follow the GitHub team URL as github.com/orgs/{organization-name}/teams/{TEAM-NAME})

Note: You CANNOT assign multiple roles to a team/group, should create a new role with suitable permissions instead.

Docs-V0.57.x: Registering a piped

Mon, 01 Jan 0001 00:00:00 +0000

The list of pipeds is shown on the Settings page. Anyone who has the project admin role can register a new piped by clicking on the +ADD button.

Registering a new piped

Docs-V0.57.x: Configuration reference

Mon, 01 Jan 0001 00:00:00 +0000

apiVersion: pipecd.dev/v1beta1
kind: ControlPlane
spec:
  address: https://your-pipecd-address
  ...

Control Plane Configuration

Field	Type	Description	Required
stateKey	string	A randomly generated string used to sign oauth state.	Yes
datastore	DataStore	Storage for storing application, deployment data.	Yes
filestore	FileStore	File storage for storing deployment logs and application states.	Yes
cache	Cache	Internal cache configuration.	No
address	string	The address to the control plane. This is required if SSO is enabled.	No
insightCollector	InsightCollector	Option to run collector of Insights feature.	No
sharedSSOConfigs	[]SharedSSOConfig	List of shared SSO configurations that can be used by any projects.	No
projects	[]Project	List of debugging/quickstart projects. Please note that do not use this to configure the projects running in the production.	No

DataStore

Field	Type	Description	Required
type	string	Which type of data store should be used. Can be one of the following values `FIRESTORE`, `MYSQL`.	Yes
config	DataStoreConfig	Specific configuration for the datastore type. This must be one of these DataStoreConfig.	Yes

DataStoreConfig

Must be one of the following objects:

DataStoreFireStoreConfig

Field	Type	Description	Required
namespace	string	The root path element considered as a logical namespace, e.g. `pipecd`.	Yes
environment	string	The second path element considered as a logical environment, e.g. `dev`. All pipecd collections will have path formatted according to `{namespace}/{environment}/{collection-name}`.	Yes
collectionNamePrefix	string	The prefix for collection name. This can be used to avoid conflicts with existing collections in your Firestore database.	No
project	string	The name of GCP project hosting the Firestore.	Yes
credentialsFile	string	The path to the service account file for accessing Firestores.	No

DataStoreMySQLConfig

Field	Type	Description	Required
url	string	The address to MySQL server. Should attach with the database port info as `127.0.0.1:3307` in case you want to use another port than the default value.	Yes
database	string	The name of database.	No (If you set it via URL)
usernameFile	string	Path to the file containing the username.	No
passwordFile	string	Path to the file containing the password.	No

FileStore

Field	Type	Description	Required
type	string	Which type of file store should be used. Can be one of the following values `GCS`, `S3`, `MINIO`	Yes
config	FileStoreConfig	Specific configuration for the filestore type. This must be one of these FileStoreConfig.	Yes

FileStoreConfig

Must be one of the following objects:

FileStoreGCSConfig

Field	Type	Description	Required
bucket	string	The bucket name.	Yes
credentialsFile	string	The path to the service account file for accessing GCS.	No

FileStoreS3Config

Field	Type	Description	Required
bucket	string	The AWS S3 bucket name.	Yes
region	string	The AWS region name.	Yes
profile	string	The AWS profile name. Default value is `default`.	No
credentialsFile	string	The path to AWS credential file. Requires only if you want to auth by specified credential file, by default PipeCD will use `$HOME/.aws/credentials` file.	No
roleARN	string	The IAM role arn to use when assuming an role. Requires only if you want to auth by `WebIdentity` pattern.	No
tokenFile	string	The path to the WebIdentity token PipeCD should use to assume a role with. Requires only if you want to auth by `WebIdentity` pattern.	No

FileStoreMinioConfig

Field	Type	Description	Required
endpoint	string	The address of Minio.	Yes
bucket	string	The bucket name.	Yes
accessKeyFile	string	The path to the access key file.	No
secretKeyFile	string	The path to the secret key file.	No
autoCreateBucket	bool	Whether the given bucket should be made automatically if not exists.	No

Cache

Field	Type	Description	Required
ttl	duration	The time that in-memory cache items are stored before they are considered as stale.	Yes

Project

Field	Type	Description	Required
id	string	The unique identifier of the project.	Yes
desc	string	The description about the project.	No
staticAdmin	ProjectStaticUser	Static admin account of the project.	Yes

ProjectStaticUser

Field	Type	Description	Required
username	string	The username string.	Yes
passwordHash	string	The bcrypt hashed value of the password string.	Yes

InsightCollector

Field	Type	Description	Required
application	InsightCollectorApplication	Application metrics collector.	No
deployment	InsightCollectorDeployment	Deployment metrics collector.	No

InsightCollectorApplication

Field	Type	Description	Required
enabled	bool	Whether to enable. Default is `true`	No
schedule	string	When collector will be executed. Default is `0 * * * *`	No

InsightCollectorDeployment

Field	Type	Description	Required
enabled	bool	Whether to enable. Default is `true`	No
schedule	string	When collector will be executed. Default is `30 * * * *`	No
chunkMaxCount	int	The maximum number of deployment items could be stored in a chunk. Default is `1000`	No

SharedSSOConfig

Field	Type	Description	Required
name	string	The unique name of the configuration.	Yes
provider	string	The SSO service provider. Currently, only `GITHUB` and `OIDC` is supported.	Yes
sessionTtl	int	The time to live of session for SSO login. Unit is `hour`. Default is 7 * 24 hours.	No
github	SSOConfigGitHub	GitHub sso configuration.	No
oidc	SSOConfigOIDC	OIDC sso configuration.	No

SSOConfigGitHub

Field	Type	Description	Required
clientId	string	The client id string of GitHub oauth app.	Yes
clientSecret	string	The client secret string of GitHub oauth app.	Yes
baseUrl	string	The address of GitHub service. Required if enterprise.	No
uploadUrl	string	The upload url of GitHub service.	No
proxyUrl	string	The address of the proxy used while communicating with the GitHub service.	No

SSOConfigOIDC

Field	Type	Description	Required
clientId	string	The client id string of OpenID Connect oauth app.	Yes
clientSecret	string	The client secret string of OpenID Connect oauth app.	Yes
issuer	string	The address of OpenID Connect service.	Yes
redirectUri	string	The address of the redirect URI.	Yes
authorizationEndpoint	string	The address of the authorization endpoint. Only set if you want to use custom authorization endpoint (still need issuer discovery).	No
tokenEndpoint	string	The address of the token endpoint. Only set if you want to use custom token endpoint (still need issuer discovery).	No
userInfoEndpoint	string	The address of the user info endpoint. Only set if you want to use custom user info endpoint (still need issuer discovery).	No
proxyUrl	string	The address of the proxy used while communicating with the OpenID Connect service.	No
scopes	[]string	Scopes to request from the OpenID Connect service. Default is `openid`. Some providers may require other scopes.	No
usernameClaimKey	string	The key name of the claim that contains the username. If not set, the default value will be chosen in the following order: `username`, `preferred_username`, `name`, `cognito:username`.	No
rolesClaimKey	string	The key name of the claim that contains the roles. If not set, the default value will be chosen in the following order: `groups`, `roles`, `custom:roles`, `custom:groups`.	No
avatarUrlClaimKey	string	The key name of the claim that contains the avatar url. If not set, the default value will be chosen in the following order: `picture`, `avatar_url`.	No

Docs-V0.57.x: Migrating applications across projects

Mon, 01 Jan 0001 00:00:00 +0000

This guide explains how to migrate pipeds and applications from one PipeCD project or control plane to another using the pipectl transfer command. This is useful when reorganizing projects, migrating to a new control plane instance, or consolidating multiple control planes.

Overview

The pipectl transfer command provides a safe, reliable way to migrate your PipeCD deployment infrastructure between control planes.

What gets transferred

Pipeds: All piped (new IDs and API keys will be generated)
Applications: All application configurations (both enabled and disabled)
Application state: Enabled/disabled status is preserved

What doesn’t get transferred

Deployment history: Past deployment records remain in the source control plane
Insights data: Historical metrics and analytics data
User accounts: User permissions and accounts are project-specific

When to use this feature

Migrating to a new control plane instance
Reorganizing projects or consolidating control planes
Moving applications between projects
Disaster recovery scenarios

Prerequisites

Before starting the migration, ensure you have:

pipectl installed: Version that includes the transfer command (v0.56.0 or later)
API keys: Valid API keys for both source and target control planes/projects

NOTE:

The application workloads will be untouched during the migration process, since this only transfers the PipeCD application configurations.
After migration, the applications will be triggered to run a new deployment by piped in the target project/control plane. Since it’s just a QUICKSYNC deployment, it’s expected to NOT having any changes to the application workloads. To ensure that, you should check to ensure your application can be triggered to run a QUICKSYNC deployment successfully without any changes in the source project/control plane.

Migration Workflow Overview

The migration process consists of three main phases:

Backup: Export data from source control plane/project to a local JSON file
Restore Pipeds: Register pipeds on target control plane/project with new IDs and keys
Restore Applications: Create applications on target control plane/project after pipeds connect

Expected Timeline:

Backup: Minutes (depending on number of applications)
Piped restore: Seconds to minutes
Piped configuration update and restart: Manual step, timing varies
Application restore: Minutes (depending on number of applications)

NOTE:

In case you worry about the application being triggered to run a new deployment while the migration is in progress, you can stop your piped agent after step (3) and restart it after the applications migration is complete.

Step-by-Step Migration Guide

Phase 1: Preparation

1.1 Create API keys with appropriate permissions

API Keys role:

For source control plane: Create API key with at least READ ONLY permission
For target control plane: Create API key with at least READ/WRITE permission

Create API keys in both control planes via the web UI:

Navigate to Settings > API Keys
Click “+ ADD” button
Select role
Copy and securely store the generated API key

1.2 Stop and document current piped

Before migration, stop your piped (from the source control plane/project) and save copies of your current piped configuration files. You’ll need to update these with new IDs and keys after the piped restore phase.

Phase 2: Backup Source Data

2.1 Run backup command

Export all pipeds and applications from the source control plane:

pipectl transfer backup \
    --address=https://source-control-plane.example.com \
    --api-key=SOURCE_API_KEY \
    --output-file=backup.json

Alternative using API key file:

pipectl transfer backup \
    --address=https://source-control-plane.example.com \
    --api-key-file=/path/to/source-api-key.key \
    --output-file=backup.json

2.2 Verify backup file

Check that the backup completed successfully:

# View backup file summary
cat backup.json | jq '{version, created_at, piped_count: (.pipeds | length), app_count: (.applications | length)}'

Expected output:

{
  "version": "1",
  "created_at": "2024-01-15T10:30:00Z",
  "pipeds": 5,
  "app_count": 42
}

Phase 3: Restore Pipeds

3.1 Register pipeds on target control plane

pipectl transfer restore piped \
    --address=https://target-control-plane.example.com \
    --api-key=TARGET_API_KEY \
    --input-file=backup.json \
    --output-file=piped-mapping.json

The command will output progress:

Restoring pipeds..., input-file: backup.json
Found 5 piped(s) in backup (created at 2024-01-15T10:30:00Z)
Registered piped, name: production-piped, old-id: abc123, new-id: def456
Registered piped, name: staging-piped, old-id: ghi789, new-id: jkl012
...
Piped restore completed. Update each piped config with the new ID and key...

3.2 Understanding the piped mapping file

The piped-mapping.json file contains the mapping between old and new piped IDs:

{
  "piped_mappings": [
    {
      "old_piped_id": "abc123...",
      "new_piped_id": "def456...",
      "new_key": "newly-issued-piped-api-key",
      "piped_name": "production-piped"
    },
    ...
  ]
}

Security Note: This file contains newly generated piped API keys. Protect it appropriately and distribute keys securely to each piped environment.

3.3 Update piped configurations

For each piped, update its configuration file with the new ID and key:

Locate the piped’s configuration file (typically piped-config.yaml)
Find the mapping for this piped in piped-mapping.json
Update the configuration:

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  projectID: target-project # Update to target project
  pipedID: def456...  # Update with new_piped_id
  pipedKeyData: newly-issued-piped-api-key  # Update with new_key
  apiAddress: target-control-plane.example.com:443  # Update to target control plane
  # ... rest of configuration remains the same

3.4 Restart piped and verify availability

After updating configurations, restart each piped agent and check it availability.

Open the target control plane web UI
Navigate to Settings > Pipeds
Confirm all pipeds show as “Online” with a green indicator
Check that repository sync has completed (may take a few minutes)

Important: Do not proceed to application restore until all pipeds are online and have completed their initial repository sync. This ensures Git repositories are registered before applications are created.

Phase 4: Restore Applications

4.1 Wait for repository synchronization

After pipeds connect, they automatically synchronize their configured Git repositories. This process registers repositories with the control plane, which is required before applications can be created.

Once your pipeds are online (green indicator in the web UI), configured Git repositories should be synced.

4.2 Restore applications

Once all pipeds are connected and repositories are synced:

pipectl transfer restore application \
    --address=https://target-control-plane.example.com \
    --api-key=TARGET_API_KEY \
    --input-file=backup.json \
    --piped-id-mapping-file=piped-mapping.json

The command will output progress:

Restoring applications...
Loaded mapping for 5 piped(s)
Restored application, name: frontend-app, old-id: app1, new-id: app101
Restored application, name: backend-api, old-id: app2, new-id: app102 (disabled)
...
Application restore completed, restored: 40, failed: 2

4.3 Understanding partial restore behavior

The restore command continues even if individual applications fail. Failed applications are logged with details:

Warning: failed to restore application frontend-app: repository not found
Warning: failed to restore application backend-api: missing piped mapping for piped xyz

Common failure reasons:

Repository not yet synced by piped
Piped mapping not found (piped wasn’t migrated)
Application configuration validation errors
Insufficient permissions

Failed applications are skipped and logged. You can manually create them later via the web UI or pipectl application add command.

4.4 Verify application creation

Check that applications were created successfully:

Open the target control plane web UI
Navigate to Applications
Verify all expected applications appear in the list
Check that enabled/disabled status matches the source

Via command line:

pipectl application list \
    --address=https://target-control-plane.example.com \
    --api-key=TARGET_API_KEY

Understanding Migration Behavior

Zero Downtime Migration

The migration process does not touch your actual workloads (Kubernetes pods, ECS tasks, Lambda functions, etc.). Your applications continue running normally on their existing infrastructure during the entire migration process.

QuickSync Deployment After Migration

When applications are created on the target control plane, the piped treats them as “new” applications and automatically triggers a QuickSync deployment strategy. This means:

Initial sync occurs: The piped compares the desired state (in Git) with the live state
Expected outcome: If your live workloads match the Git configuration, QuickSync will detect no changes and complete successfully without modifying anything
Zero downtime: Workloads remain unchanged during this process

First Deployment Behavior

Important: The initial QuickSync deployment after migration is treated as a first-time deployment. If this deployment fails:

No rollback occurs: There’s no previous “good state” to roll back to on the target control plane
Manual intervention: You’ll need to investigate and fix the issue manually
Source unaffected: Your applications continue running normally, managed by the source control plane until you decommission it

State Transition

Applications transition from “managed by source control plane” to “managed by target control plane” at the application restore phase. During this transition:

Deployment history does not carry over
Drift detection starts fresh from the current state
Application appears as “new” with no previous deployment records

Validation and Testing (optional)

After completing the migration, perform these validation steps:

5.1 Verify all pipeds are connected

pipectl piped list \
    --address=https://target-control-plane.example.com \
    --api-key=TARGET_API_KEY

All pipeds should show as online.

5.2 Verify all applications are created

pipectl application list \
    --address=https://target-control-plane.example.com \
    --api-key=TARGET_API_KEY | jq '. | length'

Compare the count with your backup file’s application count.

5.3 Check application sync status

Navigate to the Applications page in the web UI. Each application should show:

Sync status: Synced (green)
Recent deployment: QuickSync completed successfully

Rollback Considerations (optional)

When to roll back

Consider rolling back if:

Many applications fail to restore
Critical applications show sync failures (after long waiting period)

How to roll back

Since workloads are not touched during migration, rollback is straightforward:

Keep source control plane running: Don’t decommission the source control plane until you’re confident in the migration
Revert piped configurations: Update piped configs back to source control plane settings
Restart piped agents: Reconnect pipeds to source control plane
Clean up target control plane: Optionally delete migrated applications from target (they were never deployed)