Author – Sarasa Gunawardhana, Lead DevSecOps Engineer at Kodez
Read time 7mts (1,995 word count)
Imagine pushing a critical update at 3 AM and within seconds discovering your production environment is inconsistent, untraceable, and impossible to roll back. For modern enterprises running complex multi-service architectures, this nightmare is all too common. But what if you could treat every environment from development, staging, to production as a single, versioned “snapshot,” instantly reproducible and auditable?
In this blog, we unveil the power of manifest based deployment, a deceptively simple yet transformative approach that turns your CI/CD pipeline into a fortress of stability, speed, and compliance. You’ll discover how a single manifest file stored and tagged in Git becomes your definitive source of truth, slashing downtime, eliminating drift, giving you near instant rollback capabilities and unlocking measurable DevOps ROI.
if you're looking to manage deployments without relying on third-party tools like Jenkins, Bamboo, or other orchestration platforms, this method offers a lightweight, scalable, and highly effective alternative perfect for teams who value simplicity without sacrificing control.
In the fast-paced world of DevOps, managing deployments across multiple environments (development, staging, production) can quickly become overwhelming. Manual scripts, environment specific tweaks, and unversioned configurations lead to;
At its core, manifest based deployment maintains a single source of truth, a version controlled manifest file that defines an environment’s exact state. Each manifest snapshot specifies which applications to deploy, which container images and tags to use, configuration parameters, dependencies, and environment specific variables. Updates to the manifest drive new releases and rolling back to a previous manifest version restores the prior environment instantly. By storing manifests in Git (in human readable YAML, JSON, or TOML), teams gain full traceability, auditability, and consistency across development, staging, and production.
Key Manifest Components
The manifest file (e.g., manifest.yaml) is a structured file that defines the deployment state and should include all necessary details for deployment, such as:
You can use separate manifest files to handle different environments for your deployment or use a single file with environment-specific sections:
Example: Manifest.yaml
# manifest.yaml
Understanding Application Tagging Strategy: Main vs. Sub-Versioning
When managing application images, a robust tagging strategy enhances flexibility and control. In a manifest-based deployment, you can use main version tags for stable releases and sub-version tags for testing features in non-production environments.
Main Version Tags
Main version tags follow a semantic versioning pattern (e.g., 1.2.3), representing stable, production-ready releases. These tags are used across all environments, including production, and indicate a fully tested, approved state of the application.
For example: myregistry/frontend:1.2.3 (A stable release of the frontend service)
Sub-Version Tags
Sub-version tags extend the main version with a descriptive suffix (e.g., 1.2.3-featureX), used to test specific features or fixes in non-production environments like dev or staging. These tags allow developers to deploy and validate changes without affecting the mainline version until the feature is proven stable.
Example: myregistry/frontend:1.2.3-new-login (Testing a new login feature)
Example: myregistry/backend:1.1.0-bugfix-123 (Testing a fix for issue #123)
Restrictions
Sub-version tags are reserved for non-production environments. In production, only main version tags (e.g., 1.2.3) are used, ensuring stability and avoiding untested changes.
A repository (e.g., Git) is used to store and version the manifest. Storing the manifest in a VCS like Git provides several benefits:
It’s often kept in a dedicated repository or a subdirectory (e.g., deploy/manifest.yaml).
A tool (e.g., GitHub Actions, GitLab CI) is used to read the manifest and deploys to the target environment. The CI/CD pipeline reads the manifest file, compares it to the current state of the deployment target, and applies the necessary changes.
Deployment Workflow :
In the context of manifest-based deployment, a platform version refers to a specific, immutable snapshot of your entire application stack including all services, their image tags, and configurations tied to a single identifier. Unlike individual application versions (e.g., frontend:1.2.3), a platform version represents the holistic state of your deployment at a given point in time. This concept is particularly valuable in production, where stability, reproducibility, and traceability are paramount.
When deploying to production, you’re not just updating a single service, you’re managing an ecosystem of interdependent components. A platform version ensures that every piece of the puzzle (frontend, backend, databases, etc.) is aligned and tested together. By associating this state with a unique identifier, typically a Git tag like v1.0.0, you create a reference point that can be deployed, audited, or rolled back as a unit.
In a manifest-based deployment, the manifest file becomes the source of truth for defining a platform version
Example # manifest.yaml (tagged as v1.0.0)
When you create a Git tag (v1.0.0) on this manifest, it locks in the exact versions of frontend:1.2.2 and backend:1.0.0. This tag serves as the starting point for a production deployment pipeline, ensuring that the deployed state matches the tested configuration.
When deploying to production, you’re not just updating a single service, you’re managing an ecosystem of interdependent components. A platform version ensures that every piece of the puzzle (frontend, backend, databases, etc.) is aligned and tested together. By associating this state with a unique identifier typically a Git tag like v1.0.0 and you create a reference point that can be deployed, audited, or rolled back as a unit.
Client: National services provider on EC2 → ECS Fargate
Challenge: Manual blue/green scripts; rebuild images for rollbacks
Solution: Manifest based pipeline + Git tags →
- 90% faster rollback
- Zerodrift consistency
- Automated, audit ready deployments
We came into encounter with a company providing comprehensive national installation and maintenance services, struggling with a system hosted on a single Amazon EC2 instance running Docker for both production and non-production environments. Their architecture relied on three core services: a frontend user interface, a backend processing system, and an email service integration. To manage deployments, they used a blue-green strategy, maintaining the environment on that lone instance for each service.
Our assessment revealed significant inefficiencies. They depended on scripts to build Docker images and execute blue-green deployments, but lacked a proper Git workflow to manage changes. Switching to previous versions was a major pain point. they had no structured rollback process. When a deployment failed, they were forced to rebuild Docker images from scratch and redeploy, a time-consuming and error-prone ordeal. With their system’s growth in mind, The Client needed a solution that allowed rollbacks to a specific previous version with minimal downtime.
To address this, we reimagined their setup from the ground up. We replaced the single EC2 instance with an Amazon ECS cluster powered by Fargate, eliminating server management overhead. Each service now expanded into microservices was deployed as an ECS task (Currently at 22 services), scaling dynamically with demand. More critically, we introduced a manifest-based deployment approach, which marked a turning point for their operations.
This new strategy resolved their deployment woes comprehensively. The manifest file, stored in Git, provided a single source of truth for their system’s state, enabling automated deployments via a CI/CD pipeline. It eliminated the need for manual scripts and ensured consistency across environments unlike their old blue-green setup, where drift was a constant headache. Rollbacks became effortless, instead of rebuilding images, they could revert to a previous manifest platform version (e.g., a Git tag like v1.0.0) in minutes, meeting their downtime requirement. By understanding their challenges, we delivered a solution that not only modernized their infrastructure but also transformed their deployment process into a reliable, efficient workflow.
Mastering manifest based deployment isn’t just a technical upgrade, it’s a strategic advantage. By treating versioncontrolled manifests as your single source of truth, you gain stability, traceability, and rapid rollback capabilities. Strategic tagging lets you run stable and experimental releases in parallel, while Git powered workflows keep every change transparent and auditable. And with platform versions, you guarantee seamless, minimal disruption production rollouts.
Ready to elevate your deployment process with Kodez’s DevSecOps expertise. Let us help you implement a manifest based approach that delivers faster, safer, and smarter deployments, before downtime becomes your next obstacle.
