You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/walkthrough/air-gapped-azure-devops-offline-tarball.md
+77-62Lines changed: 77 additions & 62 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -40,16 +40,14 @@ flowchart LR
40
40
| Requirement | Details |
41
41
|-------------|---------|
42
42
|**Connected workstation**| A machine with internet access to download the CLI and its dependencies |
43
-
|**Node.js 22.x**| Installed on both the workstation and the agent (includes npm) |
44
43
|**[Self-hosted Azure Pipelines agent](https://learn.microsoft.com/en-us/azure/devops/pipelines/agents/agents?view=azure-devops#self-hosted-agents)**| Registered in your agent pool, running in the air-gapped network |
44
+
|**Node.js 22.x**| Installed on both the workstation and the Azure Pipelines agent (includes npm). Download of Node.js available at <https://nodejs.org/download>. |
45
45
|**Azure connectivity from agent**| The agent must reach your APIM instance's ARM endpoint (network-level only) |
46
46
|**File transfer mechanism**| A way to copy the npm cache directory into the air-gapped network |
47
47
48
-
> **On-premises Azure DevOps:** If you run [Azure DevOps Server](https://learn.microsoft.com/en-us/azure/devops/server/install/get-started?view=azure-devops-2022), the same approach applies.
Follow the remaining instructions listed in created `IDENTITY-SETUP-AZDO.md` or run `/apiops-setup-identity` prompt. This creates the necessary variable groups and and service connections.
85
+
93
86
---
94
87
95
-
##Step 3 — Generate the Lock File and Pre-Stage the npm Cache
88
+
### 2.2 Generate the Lock File and Pre-Stage the npm Cache
npm ci # populates ~/.npm/_cacache/ with every package the lock file references
102
95
```
103
96
104
-
Commit `package-lock.json` to the repository. The command `npm ci --offline` requires it.
97
+
> The command `npm ci --offline` requires a package lock file.
105
98
106
-
Then transfer the npm cache to the agent:
99
+
### 2.3 Modify Pipelines for Air-Gapped Operation
107
100
108
-
```bash
109
-
# On the workstation
110
-
tar -czf npm-cacache.tar.gz -C ~/.npm _cacache
101
+
The generated pipelines (`pipelines/run-extractor.yaml` and `pipelines/run-publisher.yaml`) need the following edits:
111
102
112
-
# Transfer npm-cacache.tar.gz into the air-gapped network, then on the agent:
113
-
mkdir -p ~/.npm
114
-
tar -xzf npm-cacache.tar.gz -C ~/.npm
115
-
```
103
+
| Edit | What to Change |
104
+
|------|----------------|
105
+
| 1. **Agent pool**| Update [pool YAML schema](https://learn.microsoft.com/en-us/azure/devops/pipelines/yaml-schema/pool?view=azure-pipelines). Replace `pool: vmImage: ubuntu-latest` with self-hosted agent pool (e.g. `pool: name: air-gapped-pool`). <br> (See next step [Configure the Azure DevOps Self-Hosted Agent](#3-configure-the-azure-devops-self-hosted-agent) for setup details.) |
106
+
| 2. **Remove NodeTool task**| Delete the `NodeTool@0` step (Node.js is pre-installed on the agent).<br> No `npmAuthenticate@0` task is needed for offline mode. |
107
+
| 3. **Use offline `npm ci`**| Change `npm ci` to `npm ci --offline`. |
116
108
117
-
> Repeat this cache transfer every time dependencies change (CLI upgrade, new package, etc.).
109
+
### 2.4 Commit `apiops` related files
118
110
111
+
For the offline-tarball workflow, commit the files that make the pipeline fully reproducible without npm registry access:
112
+
113
+
| File Name | Description |
114
+
|-----------|-------------|
115
+
|`.apiops/peterhauge-apiops-cli-<version>.tgz`| CLI package consumed by the pipelines. |
116
+
|`package.json`| Contains the `file:` dependency pointing to the tarball. |
117
+
|`package-lock.json`| Required for deterministic offline installs with `npm ci --offline`. |
## 3. Configure the Azure DevOps Self-Hosted Agent
122
136
123
137
Install and register the agent in the air-gapped network per the [self-hosted agent documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/agents/linux-agent?view=azure-devops).
124
138
139
+
### 3.1 Verify rerequisites
140
+
125
141
Verify the following:
126
142
127
143
1.**Node.js 22.x** is installed and on `PATH`
128
-
2.**npm cache is pre-staged** at the agent service account's `~/.npm/_cacache/` (see Step 3)
129
144
3.**Network access to Azure ARM** — the agent must reach `management.azure.com` (or [sovereign cloud equivalent](https://learn.microsoft.com/en-us/azure/developer/identity/national-cloud))
130
145
4.**Network access to Azure DevOps** — the agent must reach your Azure DevOps org for job dispatch
131
146
5.**Git** is installed (required by the `checkout` step)
132
147
133
148
> **Agent pool:** Add your air-gapped agents to a [dedicated agent pool](https://learn.microsoft.com/en-us/azure/devops/pipelines/agents/pools-queues?view=azure-devops) (e.g., `air-gapped-pool`) so pipelines target them explicitly.
134
149
135
-
---
136
-
137
-
## Step 5 — Modify Pipelines for Air-Gapped Operation
138
150
139
-
The generated pipelines (`pipelines/run-extractor.yaml` and `pipelines/run-publisher.yaml`) need three edits:
|**Remove NodeTool task**| Delete the `NodeTool@0` step (Node.js is pre-installed on the agent) |
145
-
|**Use offline `npm ci`**| Change `npm ci` to `npm ci --offline` so npm resolves entirely from the pre-staged cache |
151
+
### 3.2 Transfer npm cache files for offline use
146
152
147
-
No `npmAuthenticate@0` task is needed — there is no registry to authenticate against. The `--offline`flag makes npm fail fast if any package is missing from the cache instead of attempting a network call.
153
+
The command `npm ci --offline`requires package-lock.json and npm cache to be pre-populated.
148
154
149
-
> **Azure authentication:** The `AzureCLI@2` task handles Azure authentication via the service connection. The service connection injects tokens for `DefaultAzureCredential`.
150
-
151
-
---
152
-
153
-
## Step 6 — Configure Variable Groups and Service Connections
154
-
155
-
Follow the standard [Azure DevOps integration guide](../ci-cd/azure-devops.md#variable-groups-configuration) to set up:
155
+
Then transfer the npm cache to the agent:
156
156
157
-
1.**Variable group `apim-common`** — variables shared across all environments (e.g., subscription ID, tenant ID, common tags)
158
-
2.**Variable groups `apim-dev`, `apim-prod`** — environment-specific variables (e.g., APIM instance name, resource group) that override values from `apim-common`
159
-
3.**Service connections** — Azure Resource Manager connections scoped to your APIM instances; they can be referenced from either variable group
157
+
```bash
158
+
# On the workstation
159
+
tar -czf npm-cacache.tar.gz -C ~/.npm _cacache
160
160
161
-
These are configured in Azure DevOps and are injected at pipeline runtime.
161
+
# Transfer npm-cacache.tar.gz into the air-gapped network, then on the agent:
162
+
mkdir -p ~/.npm
163
+
tar -xzf npm-cacache.tar.gz -C ~/.npm
164
+
```
162
165
163
-
---
166
+
## 4 - Finish `apiops init` for pipeline
164
167
165
-
## Step 7 — Commit and Validate
168
+
If not already done, while on the air-gapped network, follow the remaining instructions listed in created `IDENTITY-SETUP-AZDO.md`. This creates the necessary variable groups and and service connections.
166
169
167
-
```bash
168
-
git add .
169
-
git commit -m "feat: air-gapped apiops setup with offline tarball"
170
-
git push
171
-
```
170
+
## 5 — Commit and Validate
172
171
173
172
Trigger the extract pipeline manually from **Pipelines → Run pipeline** and verify:
174
173
175
174
1.`npm ci --offline` completes with no network calls
176
175
2.`apiops extract` authenticates via the service connection and runs successfully
177
176
178
-
> **✅ Setup complete.** Your air-gapped apiops pipelines are now operational. The remaining sections cover ongoing maintenance and reference material — read them as needed.
177
+
> **✅ Setup complete.** Your air-gapped apiops pipelines are now operational. The remaining sections cover ongoing maintenance and troubleshooting.
179
178
180
179
---
181
180
182
181
## Upgrading the CLI Version
183
182
184
183
1. On a connected workstation, run `npm pack @peterhauge/apiops-cli` for the new version
185
184
2. Replace `.apiops/peterhauge-apiops-cli-*.tgz` with the new tarball and update the `file:` path in `package.json`
186
-
3. Regenerate `package-lock.json` (`npm install`)
185
+
3. Regenerate `package-lock.json`
186
+
```bash
187
+
npm install
188
+
```
187
189
4. Re-populate and re-transfer the npm cache (`npm ci` on the workstation, then copy `~/.npm/_cacache/`)
190
+
```bash
191
+
# On the workstation
192
+
tar -czf npm-cacache.tar.gz -C ~/.npm _cacache
193
+
194
+
# Transfer npm-cacache.tar.gz into the air-gapped network, then on the agent:
0 commit comments