diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md new file mode 100644 index 00000000..76e0efb5 --- /dev/null +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md @@ -0,0 +1,357 @@ +--- +title: "Creating Package Revisions" +type: docs +weight: 3 +description: "A step by step guide to creating a package revision in Porch" +--- + +## Prerequisites + +- Porch deployed on a Kubernetes cluster [Setup Porch Guide]({{% relref "/docs/neo-porch/3_getting_started/installing-porch.md" %}}). +- **Porchctl** CLI tool installed [Setup Porchctl Guide]({{% relref "/docs/neo-porch/3_getting_started/installing-porch.md" %}}). +- A Git repository registered with Porch [Setup Repositories Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/setting-up-repositories.md" %}}). +- **Kubectl** configured to access your cluster. + +## Tutorial Overview + +You will learn how to: + +1. Initialize a new package revision +2. Pull the package revision locally +3. Modify the package revision contents +4. Push changes back to Porch +5. Propose the package revision for review +6. Approve or reject the package revision + +{{% alert title="Understanding Terminology" color="primary" %}} +In Porch, you work with **PackageRevisions** - there is no separate "Package" resource. When we say "package" colloquially, we're referring to a PackageRevision. The `rpkg` command stands for "revision package". +{{% /alert %}} + +--- + +{{% alert title="Note" color="primary" %}} +Please note the tutorial assumes a porch repository is initialized with the "porch-test" name. +We recommended to use this for simpler copy pasting of commands otherwise replace any "porch-test" value with your repository's name in the below commands. +{{% /alert %}} + +## Step 1: Initialize Your First Package Revision + +Create a new package revision in Porch using the `init` command: + +```bash +porchctl rpkg init my-first-package \ + --namespace=default \ + --repository=porch-test \ + --workspace=v1 \ + --description="My first Porch package" +``` + +**What this does:** + +- Creates a new PackageRevision named `my-first-package` +- Places it in the `porch-test` repository +- Uses `v1` as the workspace name (must be unique within this package) +- Starts in `Draft` lifecycle state + +![Diagram](/static/images/porch/guides/init-workflow.drawio.svg) + +**Verify the package revision was created:** + +```bash +porchctl rpkg get --namespace default +``` + +You should see your package revision listed with lifecycle `Draft`: + +```bash +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.my-first-package.v1 my-first-package v1 0 false Draft porch-test +``` + +--- + +## Step 2: Pull the Package Revision Locally + +Download the package revision contents to your local filesystem: + +```bash +porchctl rpkg pull porch-test.my-first-package.v1 ./my-first-package --namespace default +``` + +**What this does:** + +- Fetches all resources from the PackageRevision +- Saves them to the `./my-first-package` directory +- Includes the Kptfile and any other resources + +![Diagram](/static/images/porch/guides/pull-workflow.drawio.svg) + +**Explore the package revision contents:** + +```bash +ls -al ./my-first-package +``` + +You'll see: + +- The `Kptfile` - PackageRevision metadata and pipeline configuration +- Other YAML files (if any were created) + +```bash +total 24 +drwxr-x--- 2 user user 4096 Nov 24 13:27 . +drwxr-xr-x 4 user user 4096 Nov 24 13:27 .. +-rw-r--r-- 1 user user 259 Nov 24 13:27 .KptRevisionMetadata +-rw-r--r-- 1 user user 177 Nov 24 13:27 Kptfile +-rw-r--r-- 1 user user 488 Nov 24 13:27 README.md +-rw-r--r-- 1 user user 148 Nov 24 13:27 package-context.yaml +``` + +**Alternatively:** + +If you have the tree command installed on your system you can use it to view the hierarchy of the package + +```bash +tree ./my-first-package/ +``` + +Should return the following output: + +```bash +my-first-package/ +├── Kptfile +├── README.md +└── package-context.yaml + +1 directory, 3 files +``` + +--- + +## Step 3: Modify the Package Revision + +Let's add a simple KRM function to the pipeline. + +Open the `Kptfile` in your editor of choice: + +```bash +vim ./my-first-package/Kptfile +``` + +Add a mutator function to the pipeline section so that your `Kptfile` looks like so: + +```yaml +apiVersion: kpt.dev/v1 +kind: Kptfile +metadata: + name: my-first-package + annotations: + config.kubernetes.io/local-config: "true" +info: + description: My first Porch package +pipeline: + mutators: + - image: gcr.io/kpt-fn/set-namespace:v0.4.1 + configMap: + namespace: production +``` + +**What this does:** + +- Adds a `set-namespace` function to the pipeline +- This function will set the namespace to `production` for all resources +- These Functions are not rendered until the package is "pushed" to porch + +**Add new resource:** + +Create a new configmap: + +```bash +vim ./my-first-package/test-config.yaml +``` + +Now add the following content to this new configmap + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: test-config +data: + key: "value" +``` + +**Save and close the file.** + +{{% alert title="Note" color="primary" %}} +Changes are LOCAL ONLY (Porch doesn't know about them yet) at this stage +{{% /alert %}} + +--- + +## Step 4: Push Changes Back to Porch + +Upload your modified package revision back to Porch: + +```bash +porchctl rpkg push porch-test.my-first-package.v1 ./my-first-package --namespace default +``` + +**What this does:** + +- Updates the PackageRevision in Porch +- Triggers rendering (executes pipeline functions) +- PackageRevision remains in `Draft` state + +![Diagram](/static/images/porch/guides/push-workflow.drawio.svg) + +**Successful output:** + +This describes how the KRM function was run by porch and has updated the namespace in our new configmap. + +```bash +[RUNNING] "gcr.io/kpt-fn/set-namespace:v0.4.1" +[PASS] "gcr.io/kpt-fn/set-namespace:v0.4.1" + Results: + [info]: namespace "" updated to "production", 1 value(s) changed +porch-test.my-first-package.v1 pushed +``` + +--- + +## Step 5: Propose the Package Revision + +Move the package revision to `Proposed` state for review: + +```bash +porchctl rpkg propose porch-test.my-first-package.v1 --namespace default +``` + +**What this does:** + +- Changes lifecycle from `Draft` to `Proposed` +- Signals the package revision is ready for review +- PackageRevision can still be modified if needed + +![Diagram](/static/images/porch/guides/propose-workflow.drawio.svg) + +{{% alert title="Note" color="primary" %}} +A lifecycle state change from `Draft` to `Proposed` means that in Git the package revision has moved from the `draft` branch to the `proposed` branch +{{% /alert %}} + +**Verify the state change:** + +```bash +porchctl rpkg get porch-test.my-first-package.v1 --namespace default +``` + +The lifecycle should now show `Proposed`. + +```bash +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.my-first-package.v1 my-first-package v1 0 false Proposed porch-test +``` + +--- + +## Step 6a: Approve the Package Revision + +If the package revision looks good, approve it to publish: + +```bash +porchctl rpkg approve porch-test.my-first-package.v1 --namespace default +``` + +**What this does:** + +- Changes PackageRevision lifecycle from `Proposed` (revision 0) to `Published` (revision 1) +- PackageRevision becomes **immutable** (content cannot be changed) +- Records who approved and when +- PackageRevision is now available for cloning/deployment + +![Diagram](/static/images/porch/guides/approve-workflow.drawio.svg) + +**Verify publication:** + +```bash +porchctl rpkg get porch-test.my-first-package.v1 --namespace default -o yaml | grep -E "lifecycle|publishedBy|publishTimestamp" +``` + +**Verify the state change:** + +```bash +porchctl rpkg get porch-test.my-first-package.v1 --namespace default +``` + +The lifecycle should now show `Published`. + +```bash +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.my-first-package.v1 my-first-package v1 1 true Published porch-test +``` + +--- + +## Step 6b: Reject the Package Revision (Alternative) + +If the package revision needs more work, reject it to return to `Draft`: + +```bash +porchctl rpkg reject porch-test.my-first-package.v1 --namespace default +``` + +**What this does:** + +- Changes lifecycle from `Proposed` back to `Draft` +- Allows further modifications +- You can then make changes and re-propose + +![Diagram](/static/images/porch/guides/reject-workflow.drawio.svg) + +If the package revision is rejected, the process begins again from Step 2 until the desired state is achieved. + +![Diagram](/static/images/porch/guides/lifecycle-workflow.drawio.svg) + +--- + +## Troubleshooting + +**PackageRevision stuck in Draft?** + +- Check readiness conditions: `porchctl rpkg get -o yaml | grep -A 5 conditions` + +**Push fails with conflict?** + +- Pull the latest version first: `porchctl rpkg pull ./dir` +- The PackageRevision may have been modified by someone else + +**Cannot modify Published PackageRevision?** + +- Published PackageRevisions are immutable +- Create a new revision using `porchctl rpkg copy` [Copying Package Revisions Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/copying-packages.md" %}}). + +--- + +## Understanding PackageRevision Names + +Porch generates PackageRevision names automatically: + +- Format: `{repoName}.{packageName}.{workspaceName}` +- Example: `porch-test.my-first-package.v1` +- The workspace name must be unique within the package +- Multiple PackageRevisions can share the same package name but have different workspaces + +--- + +## Key Concepts + +- **PackageRevision**: The Kubernetes resource managed by Porch (there is no separate "Package" resource) +- **Draft**: Work in progress, fully editable +- **Proposed**: Ready for review, still editable +- **Published**: Approved and immutable +- **Workspace**: Unique identifier for a PackageRevision within a package +- **Repository**: Git repo where PackageRevisions are stored +- **Pipeline**: KRM functions that transform PackageRevision resources +- **Revision Number**: 0 for Draft/Proposed, 1+ for Published (increments with each publication) + +--- diff --git a/static/images/porch/guides/approve-workflow.drawio.svg b/static/images/porch/guides/approve-workflow.drawio.svg new file mode 100644 index 00000000..c254a597 --- /dev/null +++ b/static/images/porch/guides/approve-workflow.drawio.svg @@ -0,0 +1,4 @@ + + + +
Package Approve Workflow
USER
porchctl rpkg approve porch-test.my-first-package.v1
PORCH

PORCH publishes your package
  • Proposed > Published
  • Creates Git tag & merges branch to main.
  • Records who approved & when
GIT REPO


YOUR PACKAGE: my-first-package-v1

📦 Status: Published < FINAL!
📝 Contains: Kptfile + pipeline + configmap.
✅ Approved by: You
🔓 Can edit: NO (immutable)

 \ No newline at end of file diff --git a/static/images/porch/guides/init-workflow.drawio.svg b/static/images/porch/guides/init-workflow.drawio.svg new file mode 100644 index 00000000..6ea27230 --- /dev/null +++ b/static/images/porch/guides/init-workflow.drawio.svg @@ -0,0 +1,4 @@ + + + +
Package Initialization Workflow
USER
porchctl rpkg init my-first-package
PORCH

GIT REPO


YOUR PACKAGE: my-first-package-v1

📦 Status: Draft                    
📝 Contains: Kptfile                              
🔓 Can edit: YES                               

PORCH creates your package
  • Creates Kptfile & Pkg from template
  • Sets Lifecycle to: Draft
  • Stores in Git branch: drafts/...
 \ No newline at end of file diff --git a/static/images/porch/guides/lifecycle-workflow.drawio.svg b/static/images/porch/guides/lifecycle-workflow.drawio.svg new file mode 100644 index 00000000..2d24fdca --- /dev/null +++ b/static/images/porch/guides/lifecycle-workflow.drawio.svg @@ -0,0 +1,4 @@ + + + +
Draft
🔓 Editable
Proposed
👀 Review
Published
🔒 Immutable
propose
approve
reject
 \ No newline at end of file diff --git a/static/images/porch/guides/propose-workflow.drawio.svg b/static/images/porch/guides/propose-workflow.drawio.svg new file mode 100644 index 00000000..85ad9f1e --- /dev/null +++ b/static/images/porch/guides/propose-workflow.drawio.svg @@ -0,0 +1,4 @@ + + + +
Package Propose Workflow
USER
porchctl rpkg propose porch-test.my-first-package.v1
PORCH

PORCH changes package state
  • Draft > Proposed
  • Signals: "Ready for review"
GIT REPO


YOUR PACKAGE: my-first-package-v1

📦 Status: Proposed < CHANGED!
📝 Contains: Kptfile + pipeline + configmap.
👀 Ready for review  
🔓 Can edit: YES (still editable) 

 \ No newline at end of file diff --git a/static/images/porch/guides/pull-workflow.drawio.svg b/static/images/porch/guides/pull-workflow.drawio.svg new file mode 100644 index 00000000..303dd01b --- /dev/null +++ b/static/images/porch/guides/pull-workflow.drawio.svg @@ -0,0 +1,4 @@ + + + +
Package Pulling Workflow
USER
porchctl rpkg pull my-first-package-v1 ./my-package
PORCH

GIT REPO


YOUR PACKAGE: my-first-package-v1

📦 Status: Draft                    
📝 Contains: Kptfile                              
🔓 Can edit: YES                               

PORCH retrieves the package contents from GIT to the user
USER File System

User System: ./my-first-package/
|
|-->📁 Kptfile
|-->📁 Other YAML files   
|-->📁 Readme.md

 \ No newline at end of file diff --git a/static/images/porch/guides/push-workflow.drawio.svg b/static/images/porch/guides/push-workflow.drawio.svg new file mode 100644 index 00000000..9c3f3cd6 --- /dev/null +++ b/static/images/porch/guides/push-workflow.drawio.svg @@ -0,0 +1,4 @@ + + + +
Package Push Workflow
USER
porchctl rpkg push porch-test.my-first-package.v1 ./my-first-package 
PORCH

PORCH receives your changes
  • Updates package files
  • Runs pipeline functions
  • Commits to Git
GIT REPO


YOUR PACKAGE: my-first-package-v1

📦 Status: Draft (still)
📝 Contains: Kptfile + pipeline + configmap.
✅ Pipeline ran: PASS
🔓 Can edit: YES                               

 \ No newline at end of file diff --git a/static/images/porch/guides/reject-workflow.drawio.svg b/static/images/porch/guides/reject-workflow.drawio.svg new file mode 100644 index 00000000..123f9f14 --- /dev/null +++ b/static/images/porch/guides/reject-workflow.drawio.svg @@ -0,0 +1,4 @@ + + + +
Package Reject Workflow
USER
porchctl rpkg reject porch-test.my-first-package.v1
PORCH

PORCH changes package state
  • Proposed > Draft
  • Package modification continues
GIT REPO


YOUR PACKAGE: my-first-package-v1

📦 Status: Draft < Back to Draft!
📝 Contains: Kptfile + pipeline + configmap.
🔓 Can edit: YES (still editable)
🔄 Can pull → modify → push → propose again 

 \ No newline at end of file