Best Practices for GitOps System Sync

PR-Based Approvals

When using GitOps System Sync, follow your established code merging process, utilizing "pull" or "merge" requests to manage approvals.

Repository Configuration

Configure each pipeline with a unique tuple of repository, branch, and folder path. This prevents potential issues such as artifacts being overwritten in Git, which could lead to unintended resource deletions during a "System to Git" sync operation.

Two-Way Sync

If GitOps is the primary interface and two-way sync is required:

• Limit changes through other interfaces (e.g., UI) to only those made by Org Admins under exceptional circumstances. This reduces the risk of "race condition" issues and ensures predictable system behavior.
• Consider assigning end users read-only roles, with Org Admins handling System Sync pipeline creation on their behalf.

Backup

For a "System to Git" sync used solely for backup, configure a separate tuple (repository, branch, and folder path) for the destination repository to avoid conflicts.

Structured Folder Usage

Utilize structured folders for "Git to System" operations. During a "System to Git" sync, Rafay enforces a structured folder approach, regardless of how artifacts are organized in Git. Avoiding structured folders may lead to unintended resource deletions.

Pipeline Creation

Org Admins should use "system user" accounts when creating pipelines for end users to ensure secure and manageable access.

Sharing Pipelines

Each "Git to System" sync operation reconciles all artifacts within the specified repository configuration, not only the artifacts that triggered the sync. This approach helps prevent out-of-sync states due to missed triggers. When sharing pipelines across projects, consider the number of resources associated with each System Sync pipeline.

Agent Considerations

Reliability

To maintain reliable System Sync operations, configure at least two agents in the repository settings. This redundancy ensures that sync operations continue even if one agent becomes unavailable.

Resource Sync Capacity

The maximum number of resources that can be reliably synced per pipeline trigger (Git to System or System to Git) varies by agent version:

• For agents on versions 2.9 or earlier, it is recommended to sync a maximum of approximately 600 resources per pipeline trigger (whether Git to System or System to Git).
• With agents on version 2.10 or later, enhancements increase the recommended maximum resource sync count to approximately 1,500.

Agent type (K8s or Docker) or resource requests/limits do not impact GitOps System Sync.

Agent Version and Updates

It is recommended that GitOps agents be updated to the latest version to leverage feature improvements, security fixes, and ensure optimal performance.

Important System Sync may fail or behave unpredictably with older agents when handling newly introduced resource types or updated spec fields.

Note It is recommended that different agents be used for GitOps System Sync and Environment Manager related activities.