Deployments

This guide walks you through creating PlatformApplication manifests and connecting your legacy application to ArgoCD. Rather than covering all deployment options, it focuses on what you need to get a migrated application running.

What You'll Learn

• What's required in a PlatformApplication manifest for migration
• How to set up the .platform folder structure
• How to connect your application to ArgoCD
• Common gotchas when migrating existing applications

Requirements

Required for Deployment

You must complete this section to run your application on the platform.

Before starting, ensure you have:

• Completed the Builds section
• Container images publishing to Artifactory
• Access to your organization's .platform repository
• ArgoCD access for your target environments

By the end of this section:

• Your repository has a .platform folder with environment overlays
• Your application is registered in the .platform repository
• ArgoCD is deploying your application

---

Understanding the Structure

Platform deployments use two repositories working together:

Your Repository                    .platform Repository
.platform/                         kubernetes/
  kubernetes/                        your-app/
    base/                              dev/
      platformapplication.yaml           kustomization.yaml → points to your repo
    dev/                               stg/
      kustomization.yaml                 kustomization.yaml
    stg/
      kustomization.yaml

Your application repository contains the PlatformApplication manifest and Kustomize overlays. The .platform repository contains references that ArgoCD watches.

When you merge to main, the build workflow updates the .platform repository, triggering ArgoCD to deploy.

For detailed anatomy, see:

• Platform Folder Anatomy — Your repo's .platform folder
• Platform Repository Anatomy — The organization's .platform repo

---

Creating the Minimum PlatformApplication

Create .platform/kubernetes/base/platformapplication.yaml with the minimum required fields:

apiVersion: meta.p6m.dev/v1alpha1
kind: PlatformApplication
metadata:
  name: your-app-name
  namespace: your-app-name
  labels:
    p6m.dev/app: your-app-name
spec:
  deployment:
    image: your-registry/applications/your-app-name:latest
    ports:
      - port: 8080
        protocol: http
    readinessProbe:
      port: 8080
      path: /health/ready

Required Fields

Field	Description
metadata.name	Unique name for your application
metadata.namespace	Kubernetes namespace (typically same as name)
spec.deployment.image	Container image (overridden by Kustomize in deployments)
spec.deployment.ports	Ports your application listens on
spec.deployment.readinessProbe	Health check endpoint for traffic routing

Common Additions for Legacy Apps

Your application likely needs additional configuration. Here's what to add and where to find details:

Need	Add to Manifest	Reference
Environment variables	spec.config	Configuration walkthrough
Secrets from cloud stores	spec.secrets	Secrets walkthrough
External access (ingress)	spec.networking.ingress	Ingress walkthrough
Resource limits	spec.deployment.resources	Basic walkthrough details

The Deployments walkthrough builds up a complete example progressively.

---

Setting Up Environment Overlays

Create Kustomize overlays for each environment you'll deploy to.

Base Kustomization

Create .platform/kubernetes/base/kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - platformapplication.yaml

Environment Overlays

Create overlays for each environment (dev, stg, prd) at .platform/kubernetes/<env>/kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../base

# Environment-specific patches go here

For examples of environment-specific patches (different replicas, log levels, etc.), see the walkthrough.

---

Connecting to ArgoCD

Your platform team manages the .platform repository and ArgoCD ApplicationSet. To register your application:

1. Commit your .platform folder — Push manifests to your main branch
2. Run the build workflow — Merging to main triggers the platform-application-manifest-dispatch action
3. Verify in .platform repository — A new folder should appear for your application
4. Check ArgoCD — Your application should appear and start syncing

First-Time Setup

The first deployment may require manual intervention from your platform team to add your application to the ArgoCD ApplicationSet. Contact them if your application doesn't appear in ArgoCD within a few minutes of the first successful build.

For ArgoCD details, see ArgoCD Integration.

---

Verifying Deployment

After ArgoCD syncs your application:

In ArgoCD

1. Navigate to your application in the ArgoCD UI
2. Check that sync status is "Synced" and health is "Healthy"
3. Use the Kinds filter to find your Pods and verify they're running

Via kubectl (if available)

# Check pods are running
kubectl get pods -n your-app-name

# Check the PlatformApplication status
kubectl get platformapplication your-app-name -n your-app-name -o yaml

# View logs
kubectl logs -n your-app-name -l p6m.dev/app=your-app-name

---

Common Migration Gotchas

These issues are common when migrating existing applications.

Namespace Conflicts

Problem: Your application name conflicts with an existing namespace.

Solution: Choose a unique name or work with your platform team to resolve the conflict.

Port Mismatches

Problem: The port in your manifest doesn't match what your application listens on.

Solution: Check your application's configuration. Common ports by framework:

Language/Framework	Common Port
Node.js/Express	3000, 8080
Python/FastAPI	8000, 8080
Java/Spring	8080
.NET	5000, 8080

Health Check Failures

Problem: Pods start but never become ready.

Diagnosis:

1. Verify your health check endpoint exists: curl http://localhost:PORT/health/ready
2. Check if the endpoint requires authentication (it shouldn't)
3. Review pod logs for startup errors

See Observability — Health Checks for implementing health endpoints.

Image Pull Errors

Problem: ArgoCD shows ImagePullBackOff or ErrImagePull.

Diagnosis:

1. Verify the image exists in Artifactory
2. Check that the image tag matches what was pushed
3. Ensure the cluster has credentials to pull from your registry

Missing Environment Variables

Problem: Application crashes due to missing configuration.

Solution: Add required environment variables to your manifest. For secrets, use spec.secrets with cloud secret store references rather than hardcoding values.

For comprehensive troubleshooting, see Deployments Troubleshooting.

---

Environment Promotion

After your dev deployment is working:

1. Test in dev — Verify the application works correctly
2. Cut a tag — Use the Cut Tag workflow to create a release
3. Promote to staging — Use the Promote workflow with environment stg
4. Test in staging — Verify again in the staging environment
5. Promote to production — Use the Promote workflow with environment prd

Each promotion updates the .platform repository with the new image digest for that environment. See Promotion for details.

---

Next Steps

Once your application is deploying successfully:

1. Add Observability incrementally for better operational visibility
2. Configure additional PlatformApplication features as needed
3. Document your application's runbook for on-call support

---

Related Documentation

• Deployments Overview — Complete deployments reference
• Walkthrough — Progressive tutorial building up features
• Platform Folder Anatomy — Detailed folder structure
• ArgoCD Integration — ArgoCD setup and usage
• Troubleshooting — Common issues and solutions