https://openchoreo.dev/assets/js/f0a9c36b.293aa677.js

1"use strict";(globalThis.webpackChunkopenchoreo=globalThis.webpackChunkopenchoreo||[]).push([[3797],{56595(e,n,t){t.r(n),t.d(n,{assets:()=>s,contentTitle:()=>c,default:()=>p,frontMatter:()=>a,metadata:()=>r,toc:()=>l});const r=JSON.parse('{"id":"developer-guide/projects-and-components/creating-a-project","title":"Creating a Project","description":"Set up a project to organize your components in OpenChoreo","source":"@site/versioned_docs/version-v1.3.x/developer-guide/projects-and-components/creating-a-project.md","sourceDirName":"developer-guide/projects-and-components","slug":"/developer-guide/projects-and-components/creating-a-project","permalink":"/docs/developer-guide/projects-and-components/creating-a-project","draft":false,"unlisted":false,"editUrl":"https://github.com/openchoreo/openchoreo.github.io/edit/main/versioned_docs/version-v1.3.x/developer-guide/projects-and-components/creating-a-project.md","tags":[],"version":"v1.3.x","lastUpdatedBy":"Ketharan","lastUpdatedAt":1789838955000,"frontMatter":{"title":"Creating a Project","description":"Set up a project to organize your components in OpenChoreo"},"sidebar":"docsSidebar","previous":{"title":"Overview","permalink":"/docs/developer-guide/projects-and-components/overview"},"next":{"title":"Creating a Component","permalink":"/docs/developer-guide/projects-and-components/creating-a-component"}}');var i=t(74848),o=t(28453);const a={title:"Creating a Project",description:"Set up a project to organize your components in OpenChoreo"},c="Creating a Project",s={},l=[{value:"What a Project Defines",id:"what-a-project-defines",level:2}

1,{value:"Creating via Backstage UI",id:"creating-via-backstage-ui",level:2},{value:"Creating via YAML",id:"creating-via-yaml",level:2},{value:"Managing Projects",id:"managing-projects",level:2},{value:"List projects",id:"list-projects",level:3},{value:"View project details",id:"view-project-details",level:3},{value:"Delete a project",id:"delete-a-project",level:3},{value:"Change deployment pipeline",id:"change-deployment-pipeline",level:3},{value:"What's Next",id:"whats-next",level:2}];function d(e){const n={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,o.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.header,{children:(0,i.jsx)(n.h1,{id:"creating-a-project",children:"Creating a Project"})}),"\n",(0,i.jsx)(n.p,{children:"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)."}),"\n",(0,i.jsx)(n.h2,{id:"what-a-project-defines",children:"What a Project Defines"}),"\n",(0,i.jsx)(n.p,{children:"A Project resource is intentionally minimal:"}),"\n",(0,i.jsxs)(n.table,{children:[(0,i.jsx)(n.thead,{children:(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.th,{children:"Field"}),(0,i.jsx)(n.th,{children:"Description"})]})}),(0,i.jsxs)(n.tbody,{children:[(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"metadata.name"})}),(0,i.jsx)(n.td,{children:"Unique name within the namespace (must be a valid Kubernetes name)"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"metadata.namespace"})}),(0,i.jsx)(n.td,{children:"The namespace this project belongs to"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"spec.deploymentPipelineRef"})}),(0,i.jsx)(n.td,{children:"Reference to a DeploymentPipeline that controls environment promotion"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"spec.type"})}),(0,i.jsx)(n.td,{children:"Reference to a ProjectType or ClusterProjectType that defines the project's infrastructure template. Immutable after creation"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"spec.parameters"})}),(0,i.jsx)(n.td,{children:"Optional values conforming to the referenced project type's parameter schema"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:"Annotations"}),(0,i.jsxs)(n.td,{children:["Optional ",(0,i.jsx)(n.code,{children:"openchoreo.dev/display-name"})," and ",(0,i.jsx)(n.code,{children:"openchoreo.dev/description"})," for human-readable metadata"]})]})]})]}),"\n",(0,i.jsx)(n.h2,{id:"creating-via-backstage-ui",children:"Creating via Backstage UI"}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsx)(n.li,{children:"Navigate to your namespace in the Backstage console"}),"\n",(0,i.jsxs)(n.li,{children:["Click ",(0,i.jsx)(n.strong,{children:"Create Project"})]}),"\n",(0,i.jsxs)(n.li,{children:["Fill in the form:","\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Namespace"}),": pre-selected from your current context"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Project Name"}),": a valid Kubernetes name"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Display Name"}),": optional human-readable name"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Description"}),": optional description"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Deployment Pipeline"}),": select from available pipelines in the namespace (defaults to ",(0,i.jsx)(n.code,{children:"default"}),")"]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["Click ",(0,i.jsx)(n.strong,{children:"Create"})]}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"The project appears immediately in the Backstage catalog."}),"\n",(0,i.jsx)(n.h2,{id:"creating-via-yaml",children:"Creating via YAML"}),"\n",(0,i.jsxs)(n.p,{children:["Create a ",(0,i.jsx)(n.code,{children:"project.yaml"})," file:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:'apiVersion: openchoreo.dev/v1alpha1\nkind: Project\nmetadata:\n  name: online-store\n  namespace: default\n  annotations:\n    openchoreo.dev/display-name: "Online Store"\n    openchoreo.dev/description: "E-commerce application components"\nspec:\n  deploymentPipelineRef:\n    kind: DeploymentPipeline\n    name: default\n  type:\n    kind: ClusterProjectType\n    name: default\n'})}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"spec.type"})," references the ",(0,i.jsx)(n.a,{href:"/docs/platform-engineer-guide/project-types",children:"ProjectType"}

1)," that defines the project's\ninfrastructure template and is required when applying manifests directly. Projects created through the OpenChoreo API\nor the Backstage UI default to the platform's ",(0,i.jsx)(n.code,{children:"default"})," ClusterProjectType when no type is chosen. The field is\nimmutable after creation. If the type declares a parameter schema, supply values through ",(0,i.jsx)(n.code,{children:"spec.parameters"}),"."]}),"\n",(0,i.jsx)(n.p,{children:"You can also generate a Project manifest (and one ProjectReleaseBinding per pipeline environment) from a type's\nschema:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"occ project scaffold online-store --clusterprojecttype default\n"})}),"\n",(0,i.jsx)(n.p,{children:"Apply it:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"kubectl apply -f project.yaml\n"})}),"\n",(0,i.jsx)(n.p,{children:"Or using the occ CLI:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"occ apply -f project.yaml\n"})}),"\n",(0,i.jsx)(n.admonition,{title:"Default Resources",type:"tip",children:(0,i.jsxs)(n.p,{children:["When OpenChoreo is installed, a ",(0,i.jsx)(n.code,{children:"default"})," project with a ",(0,i.jsx)(n.code,{children:"default"})," deployment pipeline is created automatically. You only need to create additional projects if you want separate deployment pipelines or logical groupings."]})}),"\n",(0,i.jsx)(n.h2,{id:"managing-projects",children:"Managing Projects"}),"\n",(0,i.jsx)(n.h3,{id:"list-projects",children:"List projects"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"occ project list --namespace default\n"})}),"\n",(0,i.jsx)(n.h3,{id:"view-project-details",children:"View project details"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"occ project get online-store --namespace default\n"})}),"\n",(0,i.jsx)(n.h3,{id:"delete-a-project",children:"Delete a project"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"occ project delete online-store --namespace default\n"})}),"\n",(0,i.jsx)(n.admonition,{type:"warning",children:(0,i.jsx)(n.p,{children:"Deleting a project also deletes all components within it."})}),"\n",(0,i.jsx)(n.h3,{id:"change-deployment-pipeline",children:"Change deployment pipeline"}),"\n",(0,i.jsx)(n.p,{children:"In the Backstage UI, click the edit icon on the Deployment Pipeline card on the project page to select a different pipeline."}),"\n",(0,i.jsx)(n.h2,{id:"whats-next",children:"What's Next"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.a,{href:"/docs/developer-guide/projects-and-components/creating-a-component",children:"Creating a Component"}),": deploy a service, web app, or scheduled task within your project"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.a,{href:"/docs/developer-guide/deploying-applications/project-releases",children:"Project Releases"}),": how the project's infrastructure is versioned, bound to environments, and promoted"]}),"\n"]})]})}function p(e={}){const{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(d,{...e})}):d(e)}},28453(e,n,t){t.d(n,{R:()=>a,x:()=>c});var r=t(96540);const i={},o=r.createContext(i);function a(e){const n=r.useContext(o);return r.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function c(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:a(e.components),r.createElement(o.Provider,{value:n},e.children)}}}]);