Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 8 additions & 22 deletions book/src/framework/compat.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Compatibility testing verifies that your product remains functional when Chainli
3. Boot environment with the oldest image → run tests (baseline)
4. For each next version:
a. Pull the new Docker image
b. Upgrade N nodes (stop container, swap image, restart — DB volumes preserved)
b. Upgrade N nodes (stop container, swap image, restart — node DB volumes preserved)
c. Run tests again (mixed-version cluster)
5. Repeat until the latest version is fully deployed and tested
```
Expand All @@ -37,19 +37,19 @@ Add the following secrets to your repository (`Settings → Secrets and variable
|---|---|---|
| `PRODUCT_IAM_ROLE` | ARN of the IAM role that grants ECR pull access. Name it with your product name, for example CCV_IAM_ROLE | `arn:aws:iam::<account_id>:role/gha-smartcontractkit-<repo>` |
| `JD_REGISTRY` | Private ECR registry ID for JD images | `<production_ecr_registry_number>.dkr.ecr.us-west-2.amazonaws.com` |
| `JD_IMAGE` | Full JD image reference (used by your environment config) | `<production_ecr_registry_number>.dkr.ecr.us-west-2.amazonaws.com/job-distributor:0.12.7` |
| `JD_IMAGE` | Full JD image reference (used by your environment config) | `<production_ecr_registry_number>.dkr.ecr.us-west-2.amazonaws.com/job-distributor:0.22.1` |

Using the GitHub CLI:

```bash
gh secret set CCV_IAM_ROLE # paste the IAM role ARN
gh secret set PRODUCT_IAM_ROLE # paste the IAM role ARN
gh secret set JD_REGISTRY # paste the JD registry URL
gh secret set JD_IMAGE # paste the JD image reference
```

### Step 3 — Copy the Compat Pipeline

Copy `devenv-compat.yml` from [chainlink/sot-upgrade-workflow](https://github.com/smartcontractkit/chainlink/blob/sot-upgrade-workflow/.github/workflows/devenv-compat.yml) into your repository at `.github/workflows/devenv-compat.yml`.
Copy `devenv-compat.yml` from [chainlink](https://github.com/smartcontractkit/chainlink/blob/develop/.github/workflows/devenv-compat.yml) into your repository at `.github/workflows/devenv-compat.yml`.

The workflow performs the following on each run:

Expand All @@ -62,14 +62,14 @@ The workflow performs the following on each run:
- name: Authenticate to AWS ECR
uses: ./.github/actions/aws-ecr-auth
with:
role-to-assume: ${{ secrets.CCV_IAM_ROLE }}
role-to-assume: ${{ secrets.PRODUCT_IAM_ROLE }}
aws-region: us-east-1
registry-type: public

- name: Authenticate to AWS ECR (JD)
uses: ./.github/actions/aws-ecr-auth
with:
role-to-assume: ${{ secrets.CCV_IAM_ROLE }}
role-to-assume: ${{ secrets.PRODUCT_IAM_ROLE }}
aws-region: us-west-2
registry-type: private
registries: ${{ secrets.JD_REGISTRY }}
Expand All @@ -90,23 +90,9 @@ The workflow performs the following on each run:

### Step 4 — Add a Nightly Trigger

Compatibility tests are typically run on a nightly schedule rather than on every PR. Add a nightly workflow (or a separate trigger in the same file) that points to your product configuration:
Compatibility tests are typically run on a nightly schedule rather than on every PR. Add a nightly workflow that points to your product configuration:

```yaml
# .github/workflows/devenv-nightly-compat.yml
on:
schedule:
- cron: '0 6 * * *' # 06:00 UTC every night, after the nightly CL image is built
workflow_dispatch: # allow manual runs

jobs:
compat:
uses: ./.github/workflows/devenv-compat.yml
secrets: inherit
with:
```

See the [chainlink nightly example](https://github.com/smartcontractkit/chainlink/blob/sot-upgrade-workflow/.github/workflows/devenv-nightly-compat.yml#L42) for a complete reference.
See the [chainlink nightly example](https://github.com/smartcontractkit/chainlink/blob/develop/.github/workflows/devenv-nightly-compat.yml#L42) for a complete reference.

### Step 5 — Write Your Compatibility Tests

Expand Down
1 change: 1 addition & 0 deletions framework/.changeset/v0.15.7.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Compat testing summary update
10 changes: 6 additions & 4 deletions framework/compat.go
Original file line number Diff line number Diff line change
Expand Up @@ -47,13 +47,14 @@ type UpgradeContext struct {
type UpgradeNRollingSummaryTemplate struct {
Total int
Earliest string
Latest string
Sequence []string
}

// WriteRollingNUpgradeSummary renders an upgrade summary and writes it to ci_summary.txt
func WriteRollingNUpgradeSummary(tmpl UpgradeNRollingSummaryTemplate) error {
r, err := RenderTemplate(`
Testing upgrade sequence for previous versions:
Testing upgrade sequence to {{.Latest}} from previous versions:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
{{- range .Sequence}}
• {{.}}
Expand All @@ -79,7 +80,7 @@ type UpgradeSOTDONSummary struct {
// WriteSOTDONUpgradeSummary renders an upgrade summary and writes it to ci_summary.txt
func WriteSOTDONUpgradeSummary(tmpl UpgradeSOTDONSummary) error {
r, err := RenderTemplate(`
Testing upgrade sequence for DON versions from RANE SOT, for product {{.ProductName}}:
Testing upgrade sequence to {{.Latest}} for DON versions from RANE SOT, for product {{.ProductName}}:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
{{- range $index, $version := .Sequence}}
• {{$version}}
Expand Down Expand Up @@ -158,7 +159,7 @@ func UpgradeNProductUniqueVersionsRolling(ctx context.Context, u UpgradeContext)
DONSize: u.DonNodes,
Earliest: u.Refs[0],
Latest: u.Refs[len(u.Refs)-1],
Sequence: u.Refs,
Sequence: u.Refs[:len(u.Refs)-1],
SequenceChunks: donRefs,
},
); err != nil {
Expand Down Expand Up @@ -224,7 +225,8 @@ func UpgradeNRolling(ctx context.Context, u UpgradeContext) error {
UpgradeNRollingSummaryTemplate{
Total: len(u.Refs),
Earliest: u.Refs[0],
Sequence: u.Refs,
Latest: u.Refs[len(u.Refs)-1],
Sequence: u.Refs[:len(u.Refs)-1],
},
); err != nil {
return err
Expand Down
Loading