How to Fix Azure Jenkins Pipeline Errors

Before your Azure Jenkins pipeline can push anything to Azure Container Registry, the image must be tagged with your full ACR login server name. This is a step that trips up almost every developer on first setup, and it's because the Docker tag format for ACR is different from Docker Hub.

Your ACR login server follows the format <registryname>.azurecr.io. You need this full hostname in the tag, not just the registry name. In your Jenkinsfile, the build and tag stage should look like this:

stage('Build and Tag') {
    steps {
        sh '''
            docker build -t azure-vote-front .
            docker tag azure-vote-front myacrregistry.azurecr.io/azure-vote-front:v1
        '''
    }
}

The docker tag command here takes the locally built image (azure-vote-front) and creates a new alias for it that includes the full ACR login server path and a version label. Without this step, when you run docker push, Docker has no idea which registry to target and will either fail or attempt to push to Docker Hub by default.

If you want to use the Jenkins build number as the version tag (recommended for traceability), swap :v1 for :${env.BUILD_NUMBER} in Groovy syntax. This gives every build a unique tag in your ACR repository, which makes rollbacks much cleaner.

After this stage runs successfully, you should see no errors in the Jenkins console output, just the layer IDs confirming the tag was applied. If you see invalid reference format, double-check that there are no spaces or uppercase letters in your registry name. ACR names must be lowercase alphanumeric only.

This is the most critical step in the entire Azure Jenkins pipeline setup, and it's where most pipeline failures actually live. The Jenkins agent needs to be authenticated to ACR before it can push images. There are two approaches: using the Azure CLI (az acr login) or using a service principal with docker login directly. Both work, pick the one that fits your environment.

Option A, Azure CLI login (simpler for managed agents):

stage('ACR Authentication') {
    steps {
        sh 'az acr login --name myacrregistry'
    }
}

This approach requires the Azure CLI to be installed on the Jenkins agent and the agent's managed identity or service principal to have the AcrPush role on the registry. To verify the role is assigned, go to the Azure Portal → your ACR resource → Access Control (IAM) → Role Assignments, and confirm your service principal appears under AcrPush.

Option B, Service principal credentials (more explicit, works anywhere):

stage('ACR Authentication') {
    environment {
        ACR_CREDS = credentials('acr-service-principal')
    }
    steps {
        sh 'docker login myacrregistry.azurecr.io -u $ACR_CREDS_USR -p $ACR_CREDS_PSW'
    }
}

For Option B, store your service principal's client ID and secret as a Jenkins Username/Password credential with the ID acr-service-principal. The service principal needs the built-in AcrPush role, not Owner or Contributor, scope it narrowly to just the registry for security.

Once authentication succeeds, you'll see Login Succeeded in the Jenkins console. If you see UNAUTHORIZED, the role assignment is almost certainly missing. Give it up to five minutes after assigning the role for Azure RBAC propagation before retrying.

With authentication in place and the image correctly tagged, the push step itself is straightforward. But there are a few pipeline-specific gotchas that can still cause it to fail even when everything looks right.

stage('Push to ACR') {
    steps {
        sh 'docker push myacrregistry.azurecr.io/azure-vote-front:v1'
    }
}

Replace myacrregistry with your actual ACR login server name, the same one you used in the tag step. For example, if your registry is named contosoprod, the full push command would be docker push contosoprod.azurecr.io/azure-vote-front:v1.

Watch the Jenkins console output carefully during this stage. You should see each image layer being pushed with a progress indicator, followed by a final line like v1: digest: sha256:abc123... size: 694. That digest confirmation means the push completed and ACR has accepted the image. No digest line means something interrupted the transfer.

If the push hangs indefinitely on large images, you're likely hitting a network timeout between the Jenkins agent and the ACR endpoint. This is common when the agent is outside Azure (on-prem or a different cloud). Check that outbound HTTPS traffic to *.azurecr.io on port 443 is not being blocked by a firewall or proxy. You can test connectivity directly from the agent with curl -I https://myacrregistry.azurecr.io/v2/, a 401 response actually means connectivity is fine (you're reaching the registry, just not yet authenticated). A connection timeout means a network-level block.

Once the push succeeds, verify the image appeared in your registry by checking Azure Portal → Container registries → your registry → Repositories. The azure-vote-front repository should be listed with the v1 tag.

This is the single most overlooked step in Azure Jenkins pipeline to AKS deployments. The azure-vote-all-in-one-redis.yaml manifest file that ships with the Azure vote sample uses azuredocs/azure-vote-front as the image reference. That points to a public Docker Hub image maintained by Microsoft, not your ACR registry. If you deploy that manifest unchanged, AKS will pull Microsoft's public image and completely ignore the one you just built and pushed.

Open the manifest file and navigate to approximately line 60. You'll find a containers section that looks like this:

containers:
- name: azure-vote-front
  image: azuredocs/azure-vote-front

Change that image reference to point at your ACR registry:

containers:
- name: azure-vote-front
  image: myacrregistry.azurecr.io/azure-vote-front:v1

In a Jenkins pipeline, you'll want to automate this substitution rather than manually editing the file each time. Use sed to do an in-place replacement as part of your deploy stage:

stage('Update Manifest') {
    steps {
        sh "sed -i 's|azuredocs/azure-vote-front|myacrregistry.azurecr.io/azure-vote-front:v1|g' azure-vote-all-in-one-redis.yaml"
    }
}

Or, if you're parameterizing the version tag with the build number, pull it from an environment variable:

sh "sed -i 's|azuredocs/azure-vote-front|myacrregistry.azurecr.io/azure-vote-front:${env.BUILD_NUMBER}|g' azure-vote-all-in-one-redis.yaml"

After this stage, quickly print the relevant line to confirm the substitution worked: sh "grep 'image:' azure-vote-all-in-one-redis.yaml". If it still shows azuredocs, the sed pattern didn't match, check for extra whitespace or different quote styles in your YAML file.

With the manifest corrected, the deployment stage applies it to your AKS cluster and then verifies the load balancer came up successfully. This stage has a common Jenkins-specific problem: the --watch flag on kubectl get service blocks the pipeline indefinitely. Here's how to do it correctly.

stage('Deploy to AKS') {
    steps {
        sh 'kubectl apply -f azure-vote-all-in-one-redis.yaml'
    }
}

stage('Verify Load Balancer') {
    steps {
        script {
            def externalIp = ''
            def attempts = 0
            while (externalIp == '' && attempts < 20) {
                sleep(15)
                externalIp = sh(
                    script: "kubectl get service azure-vote-front -o jsonpath='{.status.loadBalancer.ingress[0].ip}'",
                    returnStdout: true
                ).trim()
                attempts++
            }
            if (externalIp) {
                echo "Application available at: http://${externalIp}"
            } else {
                error("Load balancer IP not assigned after 5 minutes")
            }
        }
    }
}

The kubectl apply command creates the Kubernetes load balancer service and tells AKS to schedule the pods. The verification loop polls every 15 seconds up to 20 times (5 minutes total), which is usually enough time for Azure to provision the external IP. This approach doesn't block indefinitely the way --watch does.

If your kubectl commands fail with error: the server doesn't have a resource type "service" or similar, your Jenkins agent likely hasn't been configured with the AKS kubeconfig. Run az aks get-credentials --resource-group myResourceGroup --name myAKSCluster on the agent to set it up, or add this as a pipeline step using an Azure CLI credential. The kubeconfig gets written to ~/.kube/config on the agent and persists across builds.