Skip to content

Commit c351714

Browse files
kristiyan-velkovkristiyan-velkov
committed
[feat] update azure pipeline docs
1 parent a38b41c commit c351714

File tree

1 file changed

+195
-53
lines changed

1 file changed

+195
-53
lines changed

‎content/guides/azure-pipelines.md‎

Lines changed: 195 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -23,16 +23,14 @@ This guide walks you through building and pushing Docker images using [Azure Pip
2323
- Configure Docker authentication securely.
2424
- Set up an automated pipeline to build and push images.
2525

26-
## Step 1: Configure Docker credentials
26+
## Step 1: Configure a Docker Hub service connection
2727

28-
To authenticate securely with Docker Hub:
28+
To securely authenticate with Docker Hub using Azure Pipelines:
2929

30-
1. In your Azure DevOps project, navigate to **Project Settings > Pipelines > Library**.
31-
2. Create a new **Variable Group** and add the following variables:
32-
- `DOCKER_USERNAME` — your Docker Hub username.
33-
- `DOCKER_PASSWORD` — your Docker Hub access token (mark this as **secret**).
34-
35-
These credentials will be used by the pipeline to log in to Docker Hub.
30+
1. Navigate to **Project Settings > Service Connections** in your Azure DevOps project.
31+
2. Click **New service connection > Docker Registry**.
32+
3. Choose **Docker Hub** and provide your Docker Hub credentials or access token.
33+
4. Give the service connection a recognizable name, such as `my-docker-registry`, and grant access permissions to all pipelines.
3634

3735
## Step 2: Create your pipeline
3836

@@ -49,93 +47,237 @@ pr:
4947

5048
# Define variables for reuse across the pipeline
5149
variables:
52-
imageName: '$(dockerRegistry)/$(dockerUsername)/my-image' # Docker image name with registry and username
53-
dockerRegistry: 'docker.io' # Docker registry URL (e.g., Docker Hub or private registry)
54-
dockerUsername: '$(DOCKER_USERNAME)' # Docker username from variable group or pipeline variable
55-
buildTag: '$(Build.BuildId)' # Tag the image with the unique build ID
56-
latestTag: 'latest' # Additional tag for the latest image
57-
- group: my-variable-group # Link to Azure DevOps variable group containing DOCKER_USERNAME and DOCKER_PASSWORD
58-
59-
# Define stages for the pipeline
50+
imageName: 'docker.io/$(dockerUsername)/my-image'
51+
dockerUsername: 'your-dockerhub-username' # Replace with your Docker Hub username
52+
buildTag: '$(Build.BuildId)'
53+
latestTag: 'latest'
54+
6055
stages:
6156
- stage: BuildAndPush
6257
displayName: Build and Push Docker Image
63-
# Only run this stage for the main branch and if previous steps succeeded
6458
condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
6559
jobs:
6660
- job: DockerJob
6761
displayName: Build and Push
68-
# Use the latest Ubuntu VM image for compatibility with Docker
6962
pool:
7063
vmImage: ubuntu-latest
7164
steps:
72-
# Check out the repository code
7365
- checkout: self
7466
displayName: Checkout Code
7567

76-
# Log in to Docker registry using a service connection for secure credential management
7768
- task: Docker@2
7869
displayName: Docker Login
7970
inputs:
8071
command: login
81-
containerRegistry: 'my-docker-registry' # Service connection defined in Azure DevOps
72+
containerRegistry: 'my-docker-registry' # Service connection name
8273

83-
# Build the Docker image with BuildKit for caching and efficiency
8474
- task: Docker@2
8575
displayName: Build Docker Image
8676
inputs:
8777
command: build
88-
repository: $(imageName) # Image name with registry and username
78+
repository: $(imageName)
8979
tags: |
90-
$(buildTag) # Tag with build ID
91-
$(latestTag) # Tag as latest
92-
dockerfile: './Dockerfile' # Path to Dockerfile
93-
arguments: '--cache-from $(imageName):latest' # Use cached layers from latest image
80+
$(buildTag)
81+
$(latestTag)
82+
dockerfile: './Dockerfile'
83+
arguments: '--cache-from $(imageName):latest'
9484
env:
95-
DOCKER_BUILDKIT: 1 # Enable BuildKit for faster builds and better caching
85+
DOCKER_BUILDKIT: 1
9686

97-
# Validate the built Docker image by running a simple command (e.g., version check)
98-
- script: |
99-
docker run --rm $(imageName):$(buildTag) --version
100-
displayName: Validate Docker Image
101-
continueOnError: true # Continue even if validation fails (optional)
102-
103-
# Push the Docker image to the registry
10487
- task: Docker@2
10588
displayName: Push Docker Image
10689
inputs:
10790
command: push
10891
repository: $(imageName)
10992
tags: |
110-
$(buildTag) # Push build ID tag
111-
$(latestTag) # Push latest tag
93+
$(buildTag)
94+
$(latestTag)
95+
96+
# Optional: logout for self-hosted agents
97+
- script: docker logout
98+
displayName: Docker Logout (Self-hosted only)
99+
condition: ne(variables['Agent.OS'], 'Windows_NT')
112100
```
113101
114102
## What this pipeline does
115103
104+
This pipeline automates the Docker image build and deployment process for the main branch. It ensures a secure and efficient workflow with best practices like caching, tagging, and conditional cleanup. Here's what it does:
105+
116106
- Triggers on commits and pull requests targeting the `main` branch.
117-
- Authenticates with Docker Hub (or another specified registry) using a secure Azure DevOps service connection for credential management.
118-
- Builds and tags the Docker image with the Azure build ID and a latest tag, utilizing Docker BuildKit for efficient caching.
119-
- Validates the built Docker image by running a simple command (e.g., version check) to ensure it functions as expected.
120-
- Pushes the tagged Docker images to the specified Docker registry (e.g., Docker Hub).
107+
- Authenticates securely with Docker Hub using an Azure DevOps service connection.
108+
- Builds and tags the Docker image using Docker BuildKit for caching.
109+
- Pushes both buildId and latest tags to Docker Hub.
110+
- Logs out from Docker if running on a self-hosted Linux agent.
121111

122-
---
123112

124-
## Summary
113+
## Detailed Step-by-Step Explanation
114+
115+
### Step 1: Define Pipeline Triggers
116+
117+
```yaml
118+
trigger:
119+
- main
120+
121+
pr:
122+
- main
123+
```
124+
125+
This pipeline is triggered automatically on:
126+
- Commits pushed to the `main` branch
127+
- Pull requests targeting `main` main branch
128+
129+
> [!NOTE]
130+
> Learn more: [Define pipeline triggers in Azure Pipelines](https://learn.microsoft.com/en-us/azure/devops/pipelines/build/triggers?view=azure-devops)
131+
132+
133+
### Step 2: Define Common Variables
134+
135+
```yaml
136+
variables:
137+
imageName: 'docker.io/$(dockerUsername)/my-image'
138+
dockerUsername: 'your-dockerhub-username' # Replace with your actual Docker Hub username
139+
buildTag: '$(Build.BuildId)'
140+
latestTag: 'latest'
141+
```
142+
143+
These variables ensure consistent naming, versioning, and reuse throughout the pipeline steps:
144+
145+
- `imageName`: your image path on Docker Hub
146+
- `buildTag`: a unique tag for each pipeline run
147+
- `latestTag`: a stable alias for your most recent image
148+
149+
> [!NOTE]
150+
> Learn more: [Define and use variables in Azure Pipelines](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/variables?view=azure-devops&tabs=yaml%2Cbatch)
151+
152+
153+
### Step 3: Define Pipeline Stages and Jobs
154+
155+
```yaml
156+
stages:
157+
- stage: BuildAndPush
158+
displayName: Build and Push Docker Image
159+
condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
160+
```
161+
162+
This stage executes only if:
163+
164+
- The pipeline completes successfully.
165+
- The source branch is main.
166+
167+
> [!NOTE]
168+
> Learn more: [Stage conditions in Azure Pipelines](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/stages?view=azure-devops&tabs=yaml)
169+
170+
### Step 4: Job Configuration
125171

126-
With a streamlined configuration, this Azure Pipelines CI workflow:
172+
```yaml
173+
jobs:
174+
- job: DockerJob
175+
displayName: Build and Push
176+
pool:
177+
vmImage: ubuntu-latest
178+
```
179+
180+
This job uses the latest Ubuntu VM image provided by Microsoft-hosted agents. It can be swapped with a custom pool for self-hosted agents if needed.
181+
182+
> [!NOTE]
183+
> Learn more: [Specify a pool in your pipeline](https://learn.microsoft.com/en-us/azure/devops/pipelines/agents/pools-queues?view=azure-devops&tabs=yaml%2Cbrowser)
184+
185+
#### Step 4.1 Checkout Code
186+
187+
```yaml
188+
steps:
189+
- checkout: self
190+
displayName: Checkout Code
191+
192+
```
193+
194+
This step pulls your repository code into the build agent, so the pipeline can access the Dockerfile and application files.
195+
196+
> [!NOTE]
197+
> Learn more: [checkout step documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/yaml-schema/steps-checkout?view=azure-pipelines)
127198

128-
- Automatically triggers on commits and pull requests to the main branch, building and pushing Docker images.
129-
- Authenticates securely with Docker Hub (or another registry) using an Azure DevOps service connection for credential management.
130-
- Builds and tags Docker images with the Azure build ID and a latest tag, leveraging Docker BuildKit for efficient caching.
131-
- Validates the built image with a simple command (e.g., version check) to ensure functionality.
132-
- Pushes the tagged images to the specified Docker registry (e.g., Docker Hub).
133199

134-
**You can extend this pipeline to support:**
200+
#### Step 4.2 Authenticate to Docker Hub
201+
202+
```yaml
203+
- task: Docker@2
204+
displayName: Docker Login
205+
inputs:
206+
command: login
207+
containerRegistry: 'my-docker-registry' # Replace with your service connection name
208+
```
209+
210+
Uses a preconfigured Azure DevOps Docker registry service connection to authenticate securely without exposing credentials directly.
211+
212+
> [!NOTE]
213+
> Learn more: [Use service connections for Docker Hub](https://learn.microsoft.com/en-us/azure/devops/pipelines/library/service-endpoints?view=azure-devops#docker-hub-or-others)
214+
215+
216+
#### Step 4.3 Build the Docker Image
217+
218+
```yaml
219+
- task: Docker@2
220+
displayName: Build Docker Image
221+
inputs:
222+
command: build
223+
repository: $(imageName)
224+
tags: |
225+
$(buildTag)
226+
$(latestTag)
227+
dockerfile: './Dockerfile'
228+
arguments: '--cache-from $(imageName):latest'
229+
env:
230+
DOCKER_BUILDKIT: 1
231+
```
232+
233+
This builds the image with:
234+
235+
- Two tags: one with the build ID and one as latest
236+
- Docker BuildKit for faster builds and layer caching
237+
- Cache pull from the last pushed latest tag
238+
239+
> [!NOTE]
240+
> Learn more: [Docker task for Azure Pipelines](https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/docker-v2?view=azure-pipelines&tabs=yaml)
241+
242+
243+
#### Step 4.4 Push the Docker Image
244+
```yaml
245+
- task: Docker@2
246+
displayName: Push Docker Image
247+
inputs:
248+
command: push
249+
repository: $(imageName)
250+
tags: |
251+
$(buildTag)
252+
$(latestTag)
253+
254+
```
255+
256+
This uploads both tags to Docker Hub:
257+
- `$(buildTag)` ensures traceability per run.
258+
- `latest` is used for most recent image references.
259+
260+
261+
5. Logout from Docker (Self-Hosted Agents)
262+
263+
```yaml
264+
- script: docker logout
265+
displayName: Docker Logout (Self-hosted only)
266+
condition: ne(variables['Agent.OS'], 'Windows_NT')
267+
268+
```
269+
270+
Executes docker logout at the end of the pipeline on Linux-based self-hosted agents to proactively clean up credentials and enhance security posture.
271+
272+
---
273+
274+
## Summary
135275

136-
- Multi-platform image builds for broader architecture compatibility.
137-
- Deployment stages for Helm or Kubernetes-based environments.
138-
- Integration with [Azure Container Registry (ACR)](https://learn.microsoft.com/en-us/azure/container-registry/) for private registry storage.
276+
With this Azure Pipelines CI setup, you get:
277+
- Secure Docker authentication using a built-in service connection.
278+
- Automated image building and tagging triggered by code changes.
279+
- Efficient builds leveraging Docker BuildKit cache.
280+
- Safe cleanup with logout on persistent agents.
139281

140282
---
141283

0 commit comments

Comments
 (0)