Creating a Project

A Project is a logical boundary that groups related components together. Each project is linked to a deployment pipeline that defines how components are promoted across environments (e.g., development, staging, production).

What a Project Defines

A Project resource is intentionally minimal:

Field	Description
metadata.name	Unique name within the namespace (must be a valid Kubernetes name)
metadata.namespace	The namespace this project belongs to
spec.deploymentPipelineRef	Reference to a DeploymentPipeline that controls environment promotion
spec.type	Reference to a ProjectType or ClusterProjectType that defines the project's infrastructure template. Immutable after creation
spec.parameters	Optional values conforming to the referenced project type's parameter schema
Annotations	Optional openchoreo.dev/display-name and openchoreo.dev/description for human-readable metadata

Creating via Backstage UI

1. Navigate to your namespace in the Backstage console
2. Click Create Project
3. Fill in the form:
   • Namespace: pre-selected from your current context
   • Project Name: a valid Kubernetes name
   • Display Name: optional human-readable name
   • Description: optional description
   • Deployment Pipeline: select from available pipelines in the namespace (defaults to default)
4. Click Create

The project appears immediately in the Backstage catalog.

Creating via YAML

Create a project.yaml file:

apiVersion: openchoreo.dev/v1alpha1
kind: Project
metadata:
  name: online-store
  namespace: default
  annotations:
    openchoreo.dev/display-name: "Online Store"
    openchoreo.dev/description: "E-commerce application components"
spec:
  deploymentPipelineRef:
    kind: DeploymentPipeline
    name: default
  type:
    kind: ClusterProjectType
    name: default

spec.type references the ProjectType that defines the project's infrastructure template and is required when applying manifests directly. Projects created through the OpenChoreo API or the Backstage UI default to the platform's default ClusterProjectType when no type is chosen. The field is immutable after creation. If the type declares a parameter schema, supply values through spec.parameters.

You can also generate a Project manifest (and one ProjectReleaseBinding per pipeline environment) from a type's schema:

occ project scaffold online-store --clusterprojecttype default

Apply it:

kubectl apply -f project.yaml

Or using the occ CLI:

occ apply -f project.yaml

Default Resources

When OpenChoreo is installed, a default project with a default deployment pipeline is created automatically. You only need to create additional projects if you want separate deployment pipelines or logical groupings.

Managing Projects

List projects

occ project list --namespace default

View project details

occ project get online-store --namespace default

Delete a project

occ project delete online-store --namespace default

warning

Deleting a project also deletes all components within it.

Change deployment pipeline

In the Backstage UI, click the edit icon on the Deployment Pipeline card on the project page to select a different pipeline.

What's Next

• Creating a Component: deploy a service, web app, or scheduled task within your project
• Project Releases: how the project's infrastructure is versioned, bound to environments, and promoted