Overview: From Imperative to Declarative
A traditional Dockerfile is imperative: a series of commands that build an image step by step. A CleanStart YAML spec is declarative: a specification of the desired final image, with the build process handled by CleanStart's deterministic build system.
In Dockerfile (Imperative), you specify a sequence of commands: FROM ubuntu:22.04, RUN apt-get update and install packages, RUN pip install, COPY app.py, WORKDIR, EXPOSE, and CMD.
In CleanStart YAML (Declarative), you specify what should be in the final image: base_image, copy_packages, copy_files, working_directory, entrypoint, command, and environment variables.
The key difference is that you specify what should be in the image; CleanStart handles how it gets there. This approach enables reproducible builds, automatic patching, and SLA-backed security guarantees.
Decision Framework: When to Migrate
When to Migrate to CleanStart YAML
Migrate to CleanStart YAML when production security is critical for public APIs and sensitive data environments. Migration is appropriate when image size matters because you're containerizing microservices or serverless functions, when rapid patching is important so you can get CVE patches within hours rather than days, and when reproducibility is required for compliance in financial services or government. Migration also suits standard runtimes like Python, Node.js, Go, or Java, and works best when your image is long-lived rather than being rebuilt multiple times per day from scratch.
When to Keep Dockerfiles
Keep Dockerfiles for development and test images where frequent iteration and rebuild speed matter, for highly custom builds involving your own compiled binaries or specialized toolchains, and for experimental workloads where you're exploring new approaches or prototyping. Dockerfiles are also appropriate for complex compilation steps, custom source builds with patches, and situations where your team has inexperience with CleanStart.
Hybrid Approach
Many organizations migrate critical production images to CleanStart while keeping Dockerfiles for development and non-critical services. This gives you the best of both approaches: security and reproducibility in production, flexibility in development.
Side-by-Side Migration Examples
Example 1: Simple Python Web Application
Original Dockerfile
A generic Python image is used with dependencies installed inline during build.
Migrated CleanStart YAML
A hardened, pre-scanned base image is used with dependencies declared separately and metadata specified as top-level fields.
Key Changes
The base image migrates from python:3.11-slim to cleanstart/python:3.11-prod, which is pre-scanned for vulnerabilities, minimized, and FIPS-ready. RUN commands for dependency installation are eliminated. The pip install is removed since package versions are managed separately. File copying becomes explicit with each file listed. Metadata becomes declarative top-level fields.
Example 2: Multi-Stage Build with Node.js
Original Dockerfile
Multi-stage builds separate the build stage from the runtime stage, reducing final image size.
Migrated CleanStart YAML
CleanStart YAML doesn't support multi-stage builds directly. Instead, the build stage should run locally in your CI/CD pipeline, and the YAML specifies the runtime configuration.
Key Changes
The build stage is removed and executed in CI/CD. The YAML focuses on runtime configuration and security hardening. Node packages that were installed globally become entries in the copy_packages section.
Example 3: Go Microservice with Custom Config
Original Dockerfile
A multi-stage build compiles a Go binary, sets up a non-root user, and includes security configurations.
Migrated CleanStart YAML
The build stage is removed and executed separately in your CI/CD. The YAML focuses on runtime configuration and security hardening.
Key Changes
The build stage is extracted and run separately. User management commands move to the run_commands section. File ownership is set through run commands. Health checks become declarative configuration. Non-root user configuration is specified in a dedicated section.
Example 4: Java Application with Maven
Original Dockerfile
Multi-stage build uses Maven for building and compiles a JAR file.
Migrated CleanStart YAML
The Maven build stage is removed and executed in CI/CD. The YAML specifies the Java runtime and JAR file location.
Key Changes
Maven is removed from the runtime image. The Java runtime is explicitly specified. Environment variables for Java configuration become top-level fields. The multi-stage Docker pattern is completely eliminated.
Example 5: Application with Custom Database Initialization
Original Dockerfile
PostgreSQL setup with initialization scripts.
Migrated CleanStart YAML
The migration maintains the same functionality while using a hardened base image.
Key Changes
The hardened PostgreSQL base image is used. Initialization scripts are copied to the standard location. Standard PostgreSQL environment variables are preserved. Health checks are declared declaratively.
Common Dockerfile Patterns and YAML Equivalents
Pattern 1: Environment Variables
In Dockerfile, ENV defines environment variables. In YAML, the environment section lists environment variables.
Pattern 2: User and Permissions
In Dockerfile, RUN commands create users and change ownership. In YAML, run_commands handle user creation and a dedicated user section specifies UID/GID.
Pattern 3: Port Exposure and Health Checks
In Dockerfile, EXPOSE and HEALTHCHECK are imperative. In YAML, expose_ports and healthcheck sections are declarative.
Pattern 4: Volume Mounts
In Dockerfile, VOLUME creates mounts. In YAML, a volumes section lists mount points with mode.
Pattern 5: Working Directory
In Dockerfile, WORKDIR sets directory. In YAML, working_directory is a top-level field.
Pattern 6: Package Installation
In Dockerfile, RUN with apt-get installs packages. In YAML, copy_packages lists packages for automatic installation and cleanup.
Pattern 7: Build Arguments
In Dockerfile, ARG defines build-time arguments. In YAML, labels section handles metadata and CleanStart automatically adds standard labels.
Pattern 8: Entrypoint with Shell Wrapper
In Dockerfile, COPY and ENTRYPOINT handle shell wrappers. In YAML, copy_files and entrypoint fields handle shell wrapper scripts.
Pattern 9: Security Context
In Dockerfile, RUN commands handle security. In YAML, security_context specifies non-root execution, read-only filesystem, and capability dropping.
Step-by-Step Migration Process
Phase 1: Analyze Your Dockerfile
Understand what your Dockerfile does by listing all RUN commands, COPY instructions, environment variables, and checking for multi-stage builds.
Phase 2: Prepare Your Files
If your Dockerfile has a build stage, run it separately before creating the CleanStart YAML. Pre-build compiled artifacts locally or in CI/CD. Export pinned dependency lists. Organize your project with clear structure.
Phase 3: Write CleanStart YAML Spec
Start with a template, fill in the base image, add package dependencies, copy your files with explicit source and destination, set metadata about the image, and add security context.
Phase 4: Test and Validate
Validate your YAML syntax before building. Build a test image locally. Test the image locally. Verify the entrypoint works. Scan for vulnerabilities before deploying.
Phase 5: Deploy and Monitor
Push the image to your container registry. Deploy to a staging environment. Monitor for errors during deployment. Run your integration test suite. Deploy to production once staging validation is complete.
Handling Special Cases
Compiled Binaries and Custom Tools
If your Dockerfile compiles custom binaries, you must build them separately before creating the YAML. Build locally first, then copy the pre-built binary into the CleanStart YAML.
Complex Build Steps with Multiple Dependencies
For complex build logic involving multiple compilation steps, consider either pre-building everything in CI/CD or using custom run commands.
Secrets Management
Avoid baking secrets into images. Never include API keys or sensitive data. Use BuildKit secrets for build-time access or fetch secrets at runtime.
Fallback: Keeping Your Dockerfile
If you can't fully migrate, use Dockerfile with CleanStart base images to get some security benefits while maintaining flexibility.
Migration Checklist
The following items should be completed during your migration process to ensure a thorough and successful transition from Dockerfile to YAML format:
You should analyze all RUN, COPY, ENV, and LABEL commands in your original Dockerfile. Identify any multi-stage builds and build artifacts separately. Select an appropriate CleanStart base image that matches your runtime requirements. Create a complete list of all package dependencies needed at runtime. Document all files to copy with their source and destination paths. Configure the working_directory, entrypoint, and command fields appropriately. Add all required environment variables to the YAML specification. Configure the security context with appropriate user permissions and filesystem settings. Set up health checks if your application requires them. Validate the YAML syntax before attempting to build the image. Test the image locally using docker run to verify functionality. Scan the built image for vulnerabilities using CleanStart tools. Deploy the image to a staging environment for integration testing. Run your complete integration test suite against the staged image. Compare the original and migrated images for size, functionality, and performance. Document any special configurations or deviations from standard patterns.
Verification: Comparing Original and Migrated Images
Once migrated, verify that the new image works correctly by comparing behavior.
You can build the original image, run it to capture version and filesystem information, build the migrated image, run it to capture the same information, compare the outputs, and check image sizes to verify the migrated image is smaller and more secure.
Next Steps
Understand the benefits of migrated images and how to maintain them. Build Stage Security, The 11 Build Artifacts, Helm Charts and Kubernetes, and Reproducible Builds.
Learn how to manage migrated images at scale. The Continuous Trust Loop and Supply Chain DR Plan.