Using the Kubernetes Tag Mapper

Overview

The Tag Mapper automatically deploys Kubernetes packages when Git tags matching specific patterns are pushed and successfully built. It supports multiple deployment rules per tag pattern, enabling sophisticated CI/CD workflows across different environments.

Enabling Tag Mapper

1. Go to Development Servers → Select your application
2. Open K8s CD tab
3. In Tag deployment workflow section, check Use K8s Tag Mapper
4. Set Default K8s Package Profile for mapped tags - fallback profile if rule doesn't specify one

Creating Deployment Rules

The Tag Map Rules table (in K8s CD tab) defines when and where to deploy:

Column	Description	Example
sequence	Execution order (lower = first)	1, 2, 3
tag_match_code	Git tag pattern to match	beta, rc, :all_stable_tags
k8s_create_profile_for_tag_event	Create package profile	✓ (read-only, auto-enabled)
k8s_base_profile_id	Base profile to use	my-app-beta-staging
deploy	Auto-deploy to qualifiers	✓ or ✗
selector_qualifier_ids	Target environments	staging, qa, demo

Tag Match Code Examples

• beta → matches 1.0.0-beta.5, 1.0.0-beta.42
• alpha → matches 1.0.0-alpha.1
• rc → matches 1.0.0-rc.2
• :all_stable_tags → matches 1.0.0, 2.1.3 (no prerelease)

Multi-Rule Behavior: "Last Rule Wins"

When multiple rules target the same qualifier, Muppy uses smart deduplication:

Only the last rule (highest sequence) deploys to that qualifier.

Example

Rule 1 (seq=1): Deploy to [staging, qa]
Rule 2 (seq=2): Deploy to [qa, demo]

Result:
├─ staging → Rule 1 (only rule targeting it)
├─ qa → Rule 2 (last rule wins)
└─ demo → Rule 2 (only rule targeting it)

Benefits: - Each qualifier receives exactly ONE deployment - No duplicate package upgrades - Predictable, sequential execution

Common Patterns

Pattern 1: Progressive Deployment

Deploy beta versions through testing environments:

Rule 1: tag=beta, deploy to [staging]
Rule 2: tag=beta, deploy to [qa]
Rule 3: tag=beta, deploy to [demo]

Each qualifier gets its own rule → no overlaps → all deploy.

Pattern 2: Different Profiles per Environment

Same tag, different resource allocations:

Rule 1: tag=beta, profile=beta-minimal, deploy to [staging]
Rule 2: tag=beta, profile=beta-full, deploy to [production]

Pattern 3: Manual Approval Gate

Create profile without auto-deploying:

Rule 1: tag=beta, profile=beta-test, deploy to [staging] ✓
Rule 2: tag=beta, profile=beta-prod, deploy=✗, qualifier=none

Rule 2 creates profile for manual review, doesn't deploy automatically.

Configuration Tips

1. Use Drag-Handle to reorder rules (click sequence column)
2. Check Deploy Checkbox to enable auto-deployment to qualifiers
3. Leave Deploy Unchecked to create profile-only (manual deployment later)
4. Empty Qualifiers with deploy=checked: profile created, no deployment
5. No Qualifiers + Deploy=unchecked: creates profile for manual deployment

Duplicating an Application Definition

A duplicate starts with no package profiles of its own, and the four profile fields that name a deployed release come out empty:

Field	On the duplicate
Default K8s Package Profile	empty — you choose it
K8s Package Profile for Test Pods	empty — you choose it
K8s Package Profile for Staging Pods	empty — you choose it
Base K8s Package Profile for Production Pods	empty — you choose it
Base K8s Profile for pre-release tags	kept
Default K8s Package Profile for mapped tags	kept
Tag Map Rules, including each rule's Base K8s Profile	kept

The split follows what each field points at. The first four name a release your pipelines built for this application; inherited, the duplicate would deploy the original's build under its own name. The last three name a base profile — a recipe several Application Definitions derive from — so they follow the copy and your rules keep working.

Set a profile before the first tag

Default K8s Package Profile is required as soon as Activate K8s CD is on, so the duplicate's form asks for it the next time you save. Until it is set, a matching tag also builds nothing: the webhook has no base to derive from and stops, logging 'Default K8s Package Profile' is undefined too. Aborting. Set it — and the per-environment profiles you use — right after duplicating.

Where these fields are

They live in the K8s CD tab, which appears only when Activate K8s CD is checked on the Application Definition. The two base-profile fields are mutually exclusive on screen: Default K8s Package Profile for mapped tags shows when Use K8s Tag Mapper is on, Base K8s Profile for pre-release tags when it is off.

Troubleshooting

No deployment happened: - Verify tag format matches tag_match_code (semver required) - Check GitLab pipeline succeeded before webhook fires - Verify qualifiers are selected and Deploy is checked - Enable logs: tail -f /tmp/odoo.log | grep "Tag Map Rule"

Wrong profile deployed: - Check rule sequence order (last rule wins overlapped qualifiers) - Verify base profile exists and belongs to correct K8s app

Nothing builds on a freshly duplicated Application Definition: - Its four deployment profile fields are empty by design — see Duplicating an Application Definition - Set Default K8s Package Profile at minimum, then the per-environment ones you use

Deployment to wrong qualifier: - Overlapping qualifiers? Last rule wins strategy applies - Check rule sequence - lowest sequence number executes first