From 1eed0348b7b527c0558a6e879bf304113e0143b8 Mon Sep 17 00:00:00 2001 From: Catalin-Stratulat-Ericsson Date: Thu, 27 Nov 2025 15:12:53 +0000 Subject: [PATCH 1/4] modifying repository guide --- .../managing-repositories.md | 479 ++++++++++++++++++ .../setting-up-repositories.md | 56 -- .../upgrading-packages.md | 2 +- 3 files changed, 480 insertions(+), 57 deletions(-) create mode 100644 content/en/docs/neo-porch/4_tutorials_and_how-tos/managing-repositories.md delete mode 100644 content/en/docs/neo-porch/4_tutorials_and_how-tos/setting-up-repositories.md diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/managing-repositories.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/managing-repositories.md new file mode 100644 index 00000000..57a85299 --- /dev/null +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/managing-repositories.md @@ -0,0 +1,479 @@ +--- +title: "Managing Repositories" +type: docs +weight: 3 +description: "A guide to registering, viewing, and managing repositories 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" %}}). +- **Kubectl** configured to access your cluster. +- A Git repository to register with Porch. If you need to create one, see [GitHub's Repository Guide](https://docs.github.com/en/repositories/creating-and-managing-repositories/quickstart-for-repositories). + +--- + +## Understanding Repositories + +Before Porch can manage packages, you must register repositories where those packages are stored. Repositories tell Porch: + +- Where to find package blueprints +- Where to store deployment packages +- How to authenticate with the repository + +Porch primarily supports **Git repositories** from providers like GitHub, GitLab, Gitea, Bitbucket, and other Git-compatible services. + +**Repository Types by Purpose:** + +- **Blueprint Repositories**: Contain upstream package templates and blueprints that can be cloned and customized. These are typically read-only sources of reusable configurations. +- **Deployment Repositories**: Store deployment-ready packages that are actively managed and deployed to clusters. Mark repositories as deployment repositories using the `--deployment` flag during registration. + +--- + +## Repository Types + +Porch primarily supports Git repositories for storing and managing packages. Git is the recommended and production-ready storage backend. + +### Git Repositories + +Git repositories are the primary and recommended type for use with Porch. + +**Requirements:** + +- Git repository with an initial commit (to establish main branch) +- For private repos: Personal Access Token or Basic Auth credentials + +**Supported Git hosting services:** + +- GitHub +- GitLab +- Gitea +- Bitbucket +- Any Git-compatible service + +--- + +### OCI Repositories (Experimental) + +{{% alert title="Warning" color="warning" %}} +OCI repository support is **experimental** and not actively maintained. Use at your own risk. This feature may have limitations, bugs, or breaking changes. For production deployments, use Git repositories. +{{% /alert %}} + +Porch has experimental support for OCI (Open Container Initiative) repositories that store packages as container images. This feature is not recommended for production use. + +--- + +## Registering Repositories + +Registering a repository connects Porch to your Git storage backend, allowing it to discover and manage packages. You can register repositories with various authentication methods and configuration options. + +### Register a Git Repository + +Register a Git repository with Porch: + +```bash +porchctl repo register https://github.com/example/blueprints.git \ + --namespace default \ + --name=blueprints \ + --description="Blueprint packages" \ + --branch=main +``` + +**What this does:** + +- Registers the Git repository with Porch +- Creates a Repository resource in Kubernetes +- Begins synchronizing packages from the repository + +**Example output:** + +```bash +blueprints created +``` + +**Verify registration:** + +Check that the repository was registered successfully: + +```bash +porchctl repo get blueprints --namespace default +``` + +Look for `READY: True` in the output to confirm the repository is accessible and synchronized. + +```bash +NAME TYPE CONTENT SYNC SCHEDULE DEPLOYMENT READY ADDRESS +blueprints git Package True https://github.com/example-repo/blueprints.git +``` + +**If READY shows False:** + +Inspect the detailed status to see the error message: + +```bash +porchctl repo get blueprints --namespace default -o yaml +``` + +Check the `status.conditions` section for the error details: + +```yaml +status: + conditions: + - type: Ready + status: "False" + reason: Error + message: 'failed to list remote refs: repository not found: Repository not found.' + lastTransitionTime: "2025-11-27T14:32:20Z" +``` + +**Common error messages:** + +- `failed to list remote refs: repository not found` - Repository URL is incorrect or repository doesn't exist +- `failed to resolve credentials: cannot resolve credentials in a secret /: secrets "" not found` - Authentication secret doesn't exist or name is misspelled +- `failed to resolve credentials: resolved credentials are invalid` - Credentials in the secret are invalid or malformed +- `branch "" not found in repository` - Specified branch doesn't exist in the repository +- `repository URL is empty` - Repository URL not specified in configuration +- `target branch is empty` - Branch name not specified in configuration + +--- + +### Register with Authentication + +For private repositories, provide authentication credentials: + +**Using Basic Auth:** + +```bash +porchctl repo register https://github.com/example/private-repo.git \ + --namespace default \ + --name=private-repo \ + --repo-basic-username=myusername \ + --repo-basic-password=mytoken +``` + +**Using Workload Identity (GCP):** + +```bash +porchctl repo register https://github.com/example/private-repo.git \ + --namespace default \ + --name=private-repo \ + --repo-workload-identity +``` + +{{% alert title="Note" color="primary" %}} +For production environments, use secret management solutions (external secret stores, sealed-secrets) rather than embedding credentials in commands. + +See [Authenticating to Remote Git Repositories]({{% relref "/docs/neo-porch/6_configuration_and_deployments/relevant_old_docs/git-authentication-config.md" %}}) for detailed authentication configuration. +{{% /alert %}} + +--- + +### Register with Advanced Options + +Configure additional repository settings: + +```bash +porchctl repo register https://github.com/nephio-project/catalog \ + --namespace default \ + --name=infra \ + --directory=infra \ + --deployment=true \ + --sync-schedule="*/10 * * * *" \ + --description="Infrastructure packages" +``` + +**Common flags:** + +- `--name`: Repository name in Kubernetes (defaults to last segment of URL) +- `--description`: Brief description of the repository +- `--branch`: Git branch to use (defaults to `main`) +- `--directory`: Subdirectory within repository containing packages. Use `/` for repository root, or specify a path like `/blueprints` or `infra/packages`. Leading slash is optional. +- `--deployment`: Mark as deployment repository (packages are deployment-ready) +- `--sync-schedule`: Cron expression for periodic sync (e.g., `*/10 * * * *` for every 10 minutes). +- `--repo-basic-username`: Username for basic authentication +- `--repo-basic-password`: Password/token for basic authentication +- `--repo-workload-identity`: Use workload identity for authentication + +{{% alert title="Note" color="primary" %}} +For complete command syntax and all available flags, see the [Porchctl CLI Guide]({{% relref "/docs/neo-porch/7_cli_api/relevant_old_docs/porchctl-cli-guide.md" %}}). +{{% /alert %}} + +--- + +## Basic Operations + +These operations cover the fundamental commands for viewing and managing registered repositories. + +### List Registered Repositories + +View all repositories registered with Porch: + +```bash +porchctl repo get --namespace default +``` + +**What this does:** + +- Queries Porch for all registered repositories in the specified namespace +- Displays repository type, content, sync schedule, and status +- Shows the repository address + +{{% alert title="Note" color="primary" %}} +`porchctl repo list` is an alias for `porchctl repo get` and can be used interchangeably: + +```bash +porchctl repo list --namespace default +``` + +{{% /alert %}} + +**Using kubectl:** + +You can also use kubectl to list repositories: + +```bash +kubectl get repositories -n default +``` + +List repositories across all namespaces: + +```bash +kubectl get repositories --all-namespaces +``` + +**Example output:** + +```bash +NAME TYPE CONTENT SYNC SCHEDULE DEPLOYMENT READY ADDRESS +porch-test git Package True https://github.com/example-org/test-packages.git +blueprints git Package */10 * * * * True https://github.com/example/blueprints.git +infra git Package */10 * * * * true True https://github.com/nephio-project/catalog +``` + +**Understanding the output:** + +- **NAME**: Repository name in Kubernetes +- **TYPE**: Repository type (`git` or `oci`) +- **CONTENT**: Content type (typically `Package`) +- **SYNC SCHEDULE**: Cron expression for periodic synchronization (if configured). +- **DEPLOYMENT**: Whether this is a deployment repository +- **READY**: Repository health status +- **ADDRESS**: Repository URL + +--- + +### Get Detailed Repository Information + +View complete details about a specific repository: + +```bash +porchctl repo get porch-test --namespace default -o yaml +``` + +**What this does:** + +- Retrieves the full Repository resource +- Shows configuration, authentication, and status information +- Displays in YAML format for easy reading + +**Example output:** + +```yaml +apiVersion: config.porch.kpt.dev/v1alpha1 +kind: Repository +metadata: + name: porch-test + namespace: default + creationTimestamp: "2025-11-21T16:27:27Z" +spec: + content: Package + type: git + git: + repo: https://github.com/example-org/test-packages.git + branch: main + directory: / + secretRef: + name: porch-test-auth +status: + conditions: + - type: Ready + status: "True" + reason: Ready + message: 'Repository Ready (next sync scheduled at: 2025-11-26T09:48:03Z)' + lastTransitionTime: "2025-11-26T09:45:03Z" +``` + +**Key fields to inspect:** + +- **spec.type**: Repository type (typically `git`) +- **spec.git**: Git-specific configuration (repo URL, branch, directory, credentials) +- **spec.content**: Content type stored in repository +- **status.conditions**: Repository health and sync status + - **status**: `"True"` (healthy) or `"False"` (error) + - **reason**: `Ready` or `Error` + - **message**: Detailed error message when status is False + +--- + +## Repository Synchronization + +Porch periodically synchronizes with registered repositories to discover new packages and updates. You can also trigger manual synchronization when you need immediate updates. + +### Trigger Manual Sync + +Force an immediate synchronization of a repository: + +```bash +porchctl repo sync porch-test --namespace default +``` + +**What this does:** + +- Schedules a one-time sync (minimum 1-minute delay) +- Updates packages from the repository +- Independent of periodic sync schedule + +**Example output:** + +```bash +Repository porch-test sync scheduled +``` + +--- + +### Sync Multiple Repositories + +Sync several repositories at once: + +```bash +porchctl repo sync repo1 repo2 repo3 --namespace default +``` + +--- + +### Sync All Repositories + +Sync all repositories in a namespace: + +```bash +porchctl repo sync --all --namespace default +``` + +Sync across all namespaces: + +```bash +porchctl repo sync --all --all-namespaces +``` + +--- + +### Schedule Delayed Sync + +Schedule sync with custom delay: + +```bash +# Sync in 5 minutes +porchctl repo sync porch-test --namespace default --run-once 5m + +# Sync in 2 hours 30 minutes +porchctl repo sync porch-test --namespace default --run-once 2h30m + +# Sync at specific time +porchctl repo sync porch-test --namespace default --run-once "2024-01-15T14:30:00Z" +``` + +{{% alert title="Note" color="primary" %}} +**Sync behavior:** + +- Minimum delay is 1 minute from command execution +- Updates `spec.sync.runOnceAt` field in Repository CR +- Independent of existing periodic sync schedule +- Past timestamps are automatically adjusted to minimum delay +{{% /alert %}} + +--- + +## Unregistering Repositories + +When you no longer need Porch to manage packages from a repository, you can unregister it. This removes Porch's connection to the repository without affecting the underlying Git storage. + +### Unregister a Repository + +Remove a repository from Porch: + +```bash +porchctl repo unregister porch-test --namespace default +``` + +**What this does:** + +- Removes the Repository resource from Kubernetes +- Stops synchronizing packages from the repository +- Removes Porch's cached metadata for the repository +- Does not delete the underlying Git repository or its contents + +{{% alert title="Warning" color="warning" %}} +Unregistering a repository does not delete the underlying Git repository or its contents. It only removes Porch's connection to it. +{{% /alert %}} + +**Example output:** + +```bash +porch-test unregistered +``` + +**What happens to packages:** + +- **Published packages in Git**: Remain in the Git repository and are preserved. If you re-register the same repository later, these packages will reappear when Porch synchronizes. +- **Draft/Proposed packages pushed to Git**: Also remain in Git and will reappear upon re-registration. +- **Unpushed work-in-progress packages**: Cached packages that were never pushed to Git (draft packages being edited) are removed and cannot be recovered. + +--- + +## Troubleshooting + +Common issues when working with repositories and their solutions: + +**Repository shows READY: False?** + +- Check repository URL is accessible +- Verify authentication credentials are correct +- Inspect repository conditions: `porchctl repo get -n -o yaml` +- Check Porch server logs for detailed errors + +**Packages not appearing after registration?** + +- Ensure repository has been synchronized (check SYNC SCHEDULE or trigger manual sync) +- Verify packages have valid Kptfile in repository +- Check repository directory configuration matches package location +- If re-registering a previously unregistered repository, packages in Git will reappear after sync + +**Authentication failures?** + +- For GitHub: Ensure Personal Access Token has `repo` scope +- For private repos: Verify credentials are correctly configured +- Check secret exists: `kubectl get secret -n ` + +**Sync not working?** + +- Verify cron expression syntax is correct +- Check minimum 1-minute delay for manual syncs +- Inspect repository status for sync errors + +--- + +## Key Concepts + +Important terms and concepts for working with Porch repositories: + +- **Repository**: A Git repository registered with Porch for package management. Repositories are namespace-scoped Kubernetes resources. +- **Blueprint Repository**: Contains upstream package templates that can be cloned and customized. Typically used as read-only sources. +- **Deployment Repository**: Repository marked with `--deployment` flag containing deployment-ready packages that are actively managed. +- **Sync Schedule**: Cron expression defining periodic repository synchronization (e.g., `*/10 * * * *` for every 10 minutes). +- **Content Type**: Defines what the repository stores. `Package` is the standard type for KRM configuration packages. Other types like `Function` exist for storing KRM functions. +- **Branch**: Git branch Porch monitors for packages (defaults to `main`). Each repository tracks a single branch. +- **Directory**: Subdirectory within repository where packages are located. Use `/` for root or specify a path like `/blueprints`. +- **Namespace Scope**: Repositories exist within a Kubernetes namespace. Repository names must be unique per namespace, and packages inherit the repository's namespace. The same Git repository can be registered in multiple namespaces with different names, creating isolated package views per namespace. + +--- diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/setting-up-repositories.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/setting-up-repositories.md deleted file mode 100644 index d0131412..00000000 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/setting-up-repositories.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Managing Porch Repositories -type: docs -weight: 2 -description: Tutorial on setting up Porch repositories and using them. Before Porch can manage packages, you must register the Git repositories where those packages are stored. This tells Porch where to find package blueprints and where to store deployment packages. ---- - -If you don't have a Git repository already created and initialized, follow the steps below to create and use your own Git repository. - -## Creating and initializing a Git Repository - -1. **Create a new repository** in your Git hosting service (e.g., GitHub, GitLab, Gitea, Bitbucket). - - Navigate to your user or organization page and create a new repository. - - Provide a name (e.g., `porch-repo`), description, and set visibility as needed. -2. **Initialize the repository** for the main/master branch to exist (typically done by adding a *README.md* file in the UI) or by cloning it locally and adding initial content. - -For detailed instructions on repository creation, refer to your Git hosting service documentation. [For example on GitHub](https://docs.github.com/en/repositories/creating-and-managing-repositories/quickstart-for-repositories). - -## Register a Git-Repository as a Porch-Repository - -The `porchctl` command-line tool provides a straightforward way to register a repository. - -### Command Syntax - -The basic command for registering a repository is: - -```bash -porchctl repo register REPOSITORY [flags] -``` - -For more information about the `repo` command and available flags, see the Porchctl CLI guide [Repository registration]({{% relref "/docs/neo-porch/7_cli_api/relevant_old_docs/porchctl-cli-guide.md#repository-registration" %}}). - -### Example - -This example registers a private Git repository hosted on Gitea and configures it as a deployment repository. - -```bash -# Register a Git repository with Porch -porchctl repo register http://gitea.gitea:3000/nephio/porch-test.git \ - --name=porch-test \ - --description="Test repository for Porch packages" \ - --branch=main \ - --deployment=true \ - --repo-basic-username=nephio \ - --repo-basic-password=secret -``` - -{{% alert title="Note" color="primary" %}} -Replace the Git URL, repository name, username, and password with your own values. -{{% /alert %}} - -# See Also - -In this example we demonstrate a simple HTTP Basic auth setup using a Kubernetes `Secret`. For production environments, secret management solutions are preferred (external secret stores, sealed-secrets, or platform secrets) and the avoidance of embedding plaintext credentials in scripts. - -[Authenticating to Remote Git Repositories]({{% relref "/docs/neo-porch/6_configuration_and_deployments/relevant_old_docs/git-authentication-config.md" %}}) diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/upgrading-packages.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/upgrading-packages.md index 47194a7d..29e3aab1 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/upgrading-packages.md +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/upgrading-packages.md @@ -12,7 +12,7 @@ For detailed command reference, see the [porchctl CLI guide]({{% relref "/docs/n ## Prerequisites * Porch installed in your Kubernetes cluster, along with its CLI `porchctl`. [Setup Guide]({{% relref "/docs/neo-porch/3_getting_started/installing-porch.md" %}}) -* A Git Repository registered with Porch, in this example it's assumed that the Porch-Repository's name is "porch-test". [Repository Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/setting-up-repositories" %}}) +* A Git Repository registered with Porch, in this example it's assumed that the Porch-Repository's name is "porch-test". [Repository Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/managing-repositories" %}}) ## Key Concepts From 1d0fa7fd7078617d7465a3361d85b805f10ae08d Mon Sep 17 00:00:00 2001 From: Catalin-Stratulat-Ericsson Date: Thu, 27 Nov 2025 15:20:22 +0000 Subject: [PATCH 2/4] fixed incorrect link --- .../neo-porch/4_tutorials_and_how-tos/managing-repositories.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/managing-repositories.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/managing-repositories.md index 57a85299..450d2e74 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/managing-repositories.md +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/managing-repositories.md @@ -8,7 +8,7 @@ description: "A guide to registering, viewing, and managing repositories in Porc ## 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" %}}). +- **Porchctl** CLI tool installed [Setup Porchctl Guide]({{% relref "/docs/neo-porch/3_getting_started/installing-porchctl.md" %}}). - **Kubectl** configured to access your cluster. - A Git repository to register with Porch. If you need to create one, see [GitHub's Repository Guide](https://docs.github.com/en/repositories/creating-and-managing-repositories/quickstart-for-repositories). From b59a5d07c3813754910cbbf24f8ccdec669f0c72 Mon Sep 17 00:00:00 2001 From: Catalin-Stratulat-Ericsson Date: Fri, 28 Nov 2025 17:16:57 +0000 Subject: [PATCH 3/4] guides section restructure --- .../4_tutorials_and_how-tos/_index.md | 4 +- .../managing-repositories.md | 479 ------------------ .../upgrading-packages.md | 2 +- .../working_with_package_revisions/_index.md | 7 + .../working_with_porch_repositories/_index.md | 118 +++++ .../repository-basic-usage.md | 179 +++++++ .../repository-registration.md | 143 ++++++ .../repository-synchronization.md | 88 ++++ .../repository-unregistration.md | 43 ++ 9 files changed, 581 insertions(+), 482 deletions(-) delete mode 100644 content/en/docs/neo-porch/4_tutorials_and_how-tos/managing-repositories.md create mode 100644 content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/_index.md create mode 100644 content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/_index.md create mode 100644 content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-basic-usage.md create mode 100644 content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-registration.md create mode 100644 content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-synchronization.md create mode 100644 content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-unregistration.md diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/_index.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/_index.md index e370aff4..01e845ff 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/_index.md +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/_index.md @@ -1,8 +1,8 @@ --- -title: "Tutorials & How-to's" +title: "Guides" type: docs weight: 4 -description: Tutorials in Porch +description: Guides detailing how to use Porch --- ## Overview diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/managing-repositories.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/managing-repositories.md deleted file mode 100644 index 450d2e74..00000000 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/managing-repositories.md +++ /dev/null @@ -1,479 +0,0 @@ ---- -title: "Managing Repositories" -type: docs -weight: 3 -description: "A guide to registering, viewing, and managing repositories 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-porchctl.md" %}}). -- **Kubectl** configured to access your cluster. -- A Git repository to register with Porch. If you need to create one, see [GitHub's Repository Guide](https://docs.github.com/en/repositories/creating-and-managing-repositories/quickstart-for-repositories). - ---- - -## Understanding Repositories - -Before Porch can manage packages, you must register repositories where those packages are stored. Repositories tell Porch: - -- Where to find package blueprints -- Where to store deployment packages -- How to authenticate with the repository - -Porch primarily supports **Git repositories** from providers like GitHub, GitLab, Gitea, Bitbucket, and other Git-compatible services. - -**Repository Types by Purpose:** - -- **Blueprint Repositories**: Contain upstream package templates and blueprints that can be cloned and customized. These are typically read-only sources of reusable configurations. -- **Deployment Repositories**: Store deployment-ready packages that are actively managed and deployed to clusters. Mark repositories as deployment repositories using the `--deployment` flag during registration. - ---- - -## Repository Types - -Porch primarily supports Git repositories for storing and managing packages. Git is the recommended and production-ready storage backend. - -### Git Repositories - -Git repositories are the primary and recommended type for use with Porch. - -**Requirements:** - -- Git repository with an initial commit (to establish main branch) -- For private repos: Personal Access Token or Basic Auth credentials - -**Supported Git hosting services:** - -- GitHub -- GitLab -- Gitea -- Bitbucket -- Any Git-compatible service - ---- - -### OCI Repositories (Experimental) - -{{% alert title="Warning" color="warning" %}} -OCI repository support is **experimental** and not actively maintained. Use at your own risk. This feature may have limitations, bugs, or breaking changes. For production deployments, use Git repositories. -{{% /alert %}} - -Porch has experimental support for OCI (Open Container Initiative) repositories that store packages as container images. This feature is not recommended for production use. - ---- - -## Registering Repositories - -Registering a repository connects Porch to your Git storage backend, allowing it to discover and manage packages. You can register repositories with various authentication methods and configuration options. - -### Register a Git Repository - -Register a Git repository with Porch: - -```bash -porchctl repo register https://github.com/example/blueprints.git \ - --namespace default \ - --name=blueprints \ - --description="Blueprint packages" \ - --branch=main -``` - -**What this does:** - -- Registers the Git repository with Porch -- Creates a Repository resource in Kubernetes -- Begins synchronizing packages from the repository - -**Example output:** - -```bash -blueprints created -``` - -**Verify registration:** - -Check that the repository was registered successfully: - -```bash -porchctl repo get blueprints --namespace default -``` - -Look for `READY: True` in the output to confirm the repository is accessible and synchronized. - -```bash -NAME TYPE CONTENT SYNC SCHEDULE DEPLOYMENT READY ADDRESS -blueprints git Package True https://github.com/example-repo/blueprints.git -``` - -**If READY shows False:** - -Inspect the detailed status to see the error message: - -```bash -porchctl repo get blueprints --namespace default -o yaml -``` - -Check the `status.conditions` section for the error details: - -```yaml -status: - conditions: - - type: Ready - status: "False" - reason: Error - message: 'failed to list remote refs: repository not found: Repository not found.' - lastTransitionTime: "2025-11-27T14:32:20Z" -``` - -**Common error messages:** - -- `failed to list remote refs: repository not found` - Repository URL is incorrect or repository doesn't exist -- `failed to resolve credentials: cannot resolve credentials in a secret /: secrets "" not found` - Authentication secret doesn't exist or name is misspelled -- `failed to resolve credentials: resolved credentials are invalid` - Credentials in the secret are invalid or malformed -- `branch "" not found in repository` - Specified branch doesn't exist in the repository -- `repository URL is empty` - Repository URL not specified in configuration -- `target branch is empty` - Branch name not specified in configuration - ---- - -### Register with Authentication - -For private repositories, provide authentication credentials: - -**Using Basic Auth:** - -```bash -porchctl repo register https://github.com/example/private-repo.git \ - --namespace default \ - --name=private-repo \ - --repo-basic-username=myusername \ - --repo-basic-password=mytoken -``` - -**Using Workload Identity (GCP):** - -```bash -porchctl repo register https://github.com/example/private-repo.git \ - --namespace default \ - --name=private-repo \ - --repo-workload-identity -``` - -{{% alert title="Note" color="primary" %}} -For production environments, use secret management solutions (external secret stores, sealed-secrets) rather than embedding credentials in commands. - -See [Authenticating to Remote Git Repositories]({{% relref "/docs/neo-porch/6_configuration_and_deployments/relevant_old_docs/git-authentication-config.md" %}}) for detailed authentication configuration. -{{% /alert %}} - ---- - -### Register with Advanced Options - -Configure additional repository settings: - -```bash -porchctl repo register https://github.com/nephio-project/catalog \ - --namespace default \ - --name=infra \ - --directory=infra \ - --deployment=true \ - --sync-schedule="*/10 * * * *" \ - --description="Infrastructure packages" -``` - -**Common flags:** - -- `--name`: Repository name in Kubernetes (defaults to last segment of URL) -- `--description`: Brief description of the repository -- `--branch`: Git branch to use (defaults to `main`) -- `--directory`: Subdirectory within repository containing packages. Use `/` for repository root, or specify a path like `/blueprints` or `infra/packages`. Leading slash is optional. -- `--deployment`: Mark as deployment repository (packages are deployment-ready) -- `--sync-schedule`: Cron expression for periodic sync (e.g., `*/10 * * * *` for every 10 minutes). -- `--repo-basic-username`: Username for basic authentication -- `--repo-basic-password`: Password/token for basic authentication -- `--repo-workload-identity`: Use workload identity for authentication - -{{% alert title="Note" color="primary" %}} -For complete command syntax and all available flags, see the [Porchctl CLI Guide]({{% relref "/docs/neo-porch/7_cli_api/relevant_old_docs/porchctl-cli-guide.md" %}}). -{{% /alert %}} - ---- - -## Basic Operations - -These operations cover the fundamental commands for viewing and managing registered repositories. - -### List Registered Repositories - -View all repositories registered with Porch: - -```bash -porchctl repo get --namespace default -``` - -**What this does:** - -- Queries Porch for all registered repositories in the specified namespace -- Displays repository type, content, sync schedule, and status -- Shows the repository address - -{{% alert title="Note" color="primary" %}} -`porchctl repo list` is an alias for `porchctl repo get` and can be used interchangeably: - -```bash -porchctl repo list --namespace default -``` - -{{% /alert %}} - -**Using kubectl:** - -You can also use kubectl to list repositories: - -```bash -kubectl get repositories -n default -``` - -List repositories across all namespaces: - -```bash -kubectl get repositories --all-namespaces -``` - -**Example output:** - -```bash -NAME TYPE CONTENT SYNC SCHEDULE DEPLOYMENT READY ADDRESS -porch-test git Package True https://github.com/example-org/test-packages.git -blueprints git Package */10 * * * * True https://github.com/example/blueprints.git -infra git Package */10 * * * * true True https://github.com/nephio-project/catalog -``` - -**Understanding the output:** - -- **NAME**: Repository name in Kubernetes -- **TYPE**: Repository type (`git` or `oci`) -- **CONTENT**: Content type (typically `Package`) -- **SYNC SCHEDULE**: Cron expression for periodic synchronization (if configured). -- **DEPLOYMENT**: Whether this is a deployment repository -- **READY**: Repository health status -- **ADDRESS**: Repository URL - ---- - -### Get Detailed Repository Information - -View complete details about a specific repository: - -```bash -porchctl repo get porch-test --namespace default -o yaml -``` - -**What this does:** - -- Retrieves the full Repository resource -- Shows configuration, authentication, and status information -- Displays in YAML format for easy reading - -**Example output:** - -```yaml -apiVersion: config.porch.kpt.dev/v1alpha1 -kind: Repository -metadata: - name: porch-test - namespace: default - creationTimestamp: "2025-11-21T16:27:27Z" -spec: - content: Package - type: git - git: - repo: https://github.com/example-org/test-packages.git - branch: main - directory: / - secretRef: - name: porch-test-auth -status: - conditions: - - type: Ready - status: "True" - reason: Ready - message: 'Repository Ready (next sync scheduled at: 2025-11-26T09:48:03Z)' - lastTransitionTime: "2025-11-26T09:45:03Z" -``` - -**Key fields to inspect:** - -- **spec.type**: Repository type (typically `git`) -- **spec.git**: Git-specific configuration (repo URL, branch, directory, credentials) -- **spec.content**: Content type stored in repository -- **status.conditions**: Repository health and sync status - - **status**: `"True"` (healthy) or `"False"` (error) - - **reason**: `Ready` or `Error` - - **message**: Detailed error message when status is False - ---- - -## Repository Synchronization - -Porch periodically synchronizes with registered repositories to discover new packages and updates. You can also trigger manual synchronization when you need immediate updates. - -### Trigger Manual Sync - -Force an immediate synchronization of a repository: - -```bash -porchctl repo sync porch-test --namespace default -``` - -**What this does:** - -- Schedules a one-time sync (minimum 1-minute delay) -- Updates packages from the repository -- Independent of periodic sync schedule - -**Example output:** - -```bash -Repository porch-test sync scheduled -``` - ---- - -### Sync Multiple Repositories - -Sync several repositories at once: - -```bash -porchctl repo sync repo1 repo2 repo3 --namespace default -``` - ---- - -### Sync All Repositories - -Sync all repositories in a namespace: - -```bash -porchctl repo sync --all --namespace default -``` - -Sync across all namespaces: - -```bash -porchctl repo sync --all --all-namespaces -``` - ---- - -### Schedule Delayed Sync - -Schedule sync with custom delay: - -```bash -# Sync in 5 minutes -porchctl repo sync porch-test --namespace default --run-once 5m - -# Sync in 2 hours 30 minutes -porchctl repo sync porch-test --namespace default --run-once 2h30m - -# Sync at specific time -porchctl repo sync porch-test --namespace default --run-once "2024-01-15T14:30:00Z" -``` - -{{% alert title="Note" color="primary" %}} -**Sync behavior:** - -- Minimum delay is 1 minute from command execution -- Updates `spec.sync.runOnceAt` field in Repository CR -- Independent of existing periodic sync schedule -- Past timestamps are automatically adjusted to minimum delay -{{% /alert %}} - ---- - -## Unregistering Repositories - -When you no longer need Porch to manage packages from a repository, you can unregister it. This removes Porch's connection to the repository without affecting the underlying Git storage. - -### Unregister a Repository - -Remove a repository from Porch: - -```bash -porchctl repo unregister porch-test --namespace default -``` - -**What this does:** - -- Removes the Repository resource from Kubernetes -- Stops synchronizing packages from the repository -- Removes Porch's cached metadata for the repository -- Does not delete the underlying Git repository or its contents - -{{% alert title="Warning" color="warning" %}} -Unregistering a repository does not delete the underlying Git repository or its contents. It only removes Porch's connection to it. -{{% /alert %}} - -**Example output:** - -```bash -porch-test unregistered -``` - -**What happens to packages:** - -- **Published packages in Git**: Remain in the Git repository and are preserved. If you re-register the same repository later, these packages will reappear when Porch synchronizes. -- **Draft/Proposed packages pushed to Git**: Also remain in Git and will reappear upon re-registration. -- **Unpushed work-in-progress packages**: Cached packages that were never pushed to Git (draft packages being edited) are removed and cannot be recovered. - ---- - -## Troubleshooting - -Common issues when working with repositories and their solutions: - -**Repository shows READY: False?** - -- Check repository URL is accessible -- Verify authentication credentials are correct -- Inspect repository conditions: `porchctl repo get -n -o yaml` -- Check Porch server logs for detailed errors - -**Packages not appearing after registration?** - -- Ensure repository has been synchronized (check SYNC SCHEDULE or trigger manual sync) -- Verify packages have valid Kptfile in repository -- Check repository directory configuration matches package location -- If re-registering a previously unregistered repository, packages in Git will reappear after sync - -**Authentication failures?** - -- For GitHub: Ensure Personal Access Token has `repo` scope -- For private repos: Verify credentials are correctly configured -- Check secret exists: `kubectl get secret -n ` - -**Sync not working?** - -- Verify cron expression syntax is correct -- Check minimum 1-minute delay for manual syncs -- Inspect repository status for sync errors - ---- - -## Key Concepts - -Important terms and concepts for working with Porch repositories: - -- **Repository**: A Git repository registered with Porch for package management. Repositories are namespace-scoped Kubernetes resources. -- **Blueprint Repository**: Contains upstream package templates that can be cloned and customized. Typically used as read-only sources. -- **Deployment Repository**: Repository marked with `--deployment` flag containing deployment-ready packages that are actively managed. -- **Sync Schedule**: Cron expression defining periodic repository synchronization (e.g., `*/10 * * * *` for every 10 minutes). -- **Content Type**: Defines what the repository stores. `Package` is the standard type for KRM configuration packages. Other types like `Function` exist for storing KRM functions. -- **Branch**: Git branch Porch monitors for packages (defaults to `main`). Each repository tracks a single branch. -- **Directory**: Subdirectory within repository where packages are located. Use `/` for root or specify a path like `/blueprints`. -- **Namespace Scope**: Repositories exist within a Kubernetes namespace. Repository names must be unique per namespace, and packages inherit the repository's namespace. The same Git repository can be registered in multiple namespaces with different names, creating isolated package views per namespace. - ---- diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/upgrading-packages.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/upgrading-packages.md index 29e3aab1..ce421164 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/upgrading-packages.md +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/upgrading-packages.md @@ -12,7 +12,7 @@ For detailed command reference, see the [porchctl CLI guide]({{% relref "/docs/n ## Prerequisites * Porch installed in your Kubernetes cluster, along with its CLI `porchctl`. [Setup Guide]({{% relref "/docs/neo-porch/3_getting_started/installing-porch.md" %}}) -* A Git Repository registered with Porch, in this example it's assumed that the Porch-Repository's name is "porch-test". [Repository Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/managing-repositories" %}}) +* A Git Repository registered with Porch, in this example it's assumed that the Porch-Repository's name is "porch-test". [Repository Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-registration.md" %}}) ## Key Concepts diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/_index.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/_index.md new file mode 100644 index 00000000..22ac3717 --- /dev/null +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/_index.md @@ -0,0 +1,7 @@ +--- +title: "Working with Package Revisions" +type: docs +weight: 3 +description: +--- + diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/_index.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/_index.md new file mode 100644 index 00000000..b938aa3e --- /dev/null +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/_index.md @@ -0,0 +1,118 @@ +--- +title: "Working with Porch Repositories" +type: docs +weight: 2 +description: A group of guides outlining how to interact with Porch repositories +--- + +## 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-porchctl.md" %}}). +- **Kubectl** configured to access your cluster. +- A Git repository to register with Porch. If you need to create one, see [GitHub's Repository Guide](https://docs.github.com/en/repositories/creating-and-managing-repositories/quickstart-for-repositories). + +--- + +## Understanding Repositories + +Before Porch can manage packages, you must register repositories where those packages are stored. Repositories tell Porch: + +- Where to find package blueprints +- Where to store deployment packages +- How to authenticate with the repository + +Porch primarily supports **Git repositories** from providers like GitHub, GitLab, Gitea, Bitbucket, and other Git-compatible services. + +**Repository Types by Purpose:** + +- **Blueprint Repositories**: Contain upstream package templates and blueprints that can be cloned and customized. These are typically read-only sources of reusable configurations. +- **Deployment Repositories**: Store deployment-ready packages that are actively managed and deployed to clusters. Mark repositories as deployment repositories using the `--deployment` flag during registration. + +--- + +## Repository Types + +Porch primarily supports Git repositories for storing and managing packages. Git is the recommended and production-ready storage backend. + +### Git Repositories + +Git repositories are the primary and recommended type for use with Porch. + +**Requirements:** + +- Git repository with an initial commit (to establish main branch) +- For private repos: Personal Access Token or Basic Auth credentials + +**Supported Git hosting services:** + +- GitHub +- GitLab +- Gitea +- Bitbucket +- Any Git-compatible service + +--- + +### OCI Repositories (Experimental) + +{{% alert title="Warning" color="warning" %}} +OCI repository support is **experimental** and not actively maintained. Use at your own risk. This feature may have limitations, bugs, or breaking changes. For production deployments, use Git repositories. +{{% /alert %}} + +Porch has experimental support for OCI (Open Container Initiative) repositories that store packages as container images. This feature is not recommended for production use. + +--- + +## Troubleshooting + +Common issues when working with repositories and their solutions: + +**Repository shows READY: False?** + +- Check repository URL is accessible +- Verify authentication credentials are correct +- Inspect repository conditions: `porchctl repo get -n -o yaml` +- Check Porch server logs for detailed errors + +**Packages not appearing after registration?** + +- Ensure repository has been synchronized (check SYNC SCHEDULE or trigger manual sync) +- Verify packages have valid Kptfile in repository +- Check repository directory configuration matches package location +- If re-registering a previously unregistered repository, packages in Git will reappear after sync + +**Authentication failures?** + +- For GitHub: Ensure Personal Access Token has `repo` scope +- For private repos: Verify credentials are correctly configured +- Check secret exists: `kubectl get secret -n ` + +**Need to change repository configuration?** + +- Repository settings (branch, directory, credentials) cannot be updated via porchctl +- Use `kubectl edit repository -n ` to modify the Repository resource +- Alternatively, unregister and re-register the repository with new settings + +**Sync not working?** + +- Verify cron expression syntax is correct +- Check minimum 1-minute delay for manual syncs +- Inspect repository status for sync errors + +--- + +## Key Concepts + +Important terms and concepts for working with Porch repositories: + +- **Repository**: A Git repository registered with Porch for package management. Repositories are namespace-scoped Kubernetes resources. +- **Blueprint Repository**: Contains upstream package templates that can be cloned and customized. Typically used as read-only sources. +- **Deployment Repository**: Repository marked with `--deployment` flag containing deployment-ready packages that are actively managed. +- **Sync Schedule**: Cron expression defining periodic repository synchronization (e.g., `*/10 * * * *` for every 10 minutes). +- **Content Type**: Defines what the repository stores. `Package` is the standard type for KRM configuration packages. Other types like `Function` exist for storing KRM functions. +- **Branch**: Git branch Porch monitors for packages (defaults to `main`). Each repository tracks a single branch. +- **Directory**: Subdirectory within repository where packages are located. Use `/` for root or specify a path like `/blueprints`. +- **Namespace Scope**: Repositories exist within a Kubernetes namespace. Repository names must be unique per namespace, and packages inherit the repository's namespace. The same Git repository can be registered in multiple namespaces with different names, creating isolated package views per namespace. + +--- diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-basic-usage.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-basic-usage.md new file mode 100644 index 00000000..cc438aa6 --- /dev/null +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-basic-usage.md @@ -0,0 +1,179 @@ +--- +title: "Repositories Basic Usage" +type: docs +weight: 4 +description: "A basic usage of repositories guide in Porch" +--- + +## Basic Operations + +These operations cover the fundamental commands for viewing and managing registered repositories. + +### List Registered Repositories + +View all repositories registered with Porch: + +```bash +porchctl repo get --namespace default +``` + +**What this does:** + +- Queries Porch for all registered repositories in the specified namespace +- Displays repository type, content, sync schedule, and status +- Shows the repository address + +{{% alert title="Note" color="primary" %}} +`porchctl repo list` is an alias for `porchctl repo get` and can be used interchangeably: + +```bash +porchctl repo list --namespace default +``` + +{{% /alert %}} + +**Using kubectl:** + +You can also use kubectl to list repositories: + +```bash +kubectl get repositories -n default +``` + +List repositories across all namespaces: + +```bash +kubectl get repositories --all-namespaces +``` + +**Example output:** + +```bash +NAME TYPE CONTENT SYNC SCHEDULE DEPLOYMENT READY ADDRESS +porch-test git Package True https://github.com/example-org/test-packages.git +blueprints git Package */10 * * * * True https://github.com/example/blueprints.git +infra git Package */10 * * * * true True https://github.com/nephio-project/catalog +``` + +**Understanding the output:** + +- **NAME**: Repository name in Kubernetes +- **TYPE**: Repository type (`git` or `oci`) +- **CONTENT**: Content type (typically `Package`) +- **SYNC SCHEDULE**: Cron expression for periodic synchronization (if configured). +- **DEPLOYMENT**: Whether this is a deployment repository +- **READY**: Repository health status +- **ADDRESS**: Repository URL + +--- + +### Get Detailed Repository Information + +View complete details about a specific repository: + +```bash +porchctl repo get porch-test --namespace default -o yaml +``` + +**What this does:** + +- Retrieves the full Repository resource +- Shows configuration, authentication, and status information +- Displays in YAML format for easy reading + +**Example output:** + +```yaml +apiVersion: config.porch.kpt.dev/v1alpha1 +kind: Repository +metadata: + name: porch-test + namespace: default + creationTimestamp: "2025-11-21T16:27:27Z" +spec: + content: Package + type: git + git: + repo: https://github.com/example-org/test-packages.git + branch: main + directory: / + secretRef: + name: porch-test-auth +status: + conditions: + - type: Ready + status: "True" + reason: Ready + message: 'Repository Ready (next sync scheduled at: 2025-11-26T09:48:03Z)' + lastTransitionTime: "2025-11-26T09:45:03Z" +``` + +**Key fields to inspect:** + +- **spec.type**: Repository type (typically `git`) +- **spec.git**: Git-specific configuration (repo URL, branch, directory, credentials) +- **spec.content**: Content type stored in repository +- **status.conditions**: Repository health and sync status + - **status**: `"True"` (healthy) or `"False"` (error) + - **reason**: `Ready` or `Error` + - **message**: Detailed error message when status is False + +--- + +### Update Repository Configuration + +Updating repository settings is uncommon in practice. The typical workflow is to unregister and re-register the repository with new details. However, if you need to modify an existing repository configuration, you can edit the Kubernetes resource directly. + +{{% alert title="Note" color="primary" %}} +There is no `porchctl repo update` command. Repository updates must be done using kubectl. +{{% /alert %}} + +**Edit a repository:** + +```bash +kubectl edit repository porch-test -n default +``` + +This opens the repository configuration in your default editor. You can modify fields under `spec.git` such as: + +- `branch`: Change the Git branch +- `directory`: Update the package directory path +- `secretRef.name`: Change authentication credentials +- `deployment`: Toggle deployment repository flag + +**Example using kubectl patch:** + +```bash +# Change branch +kubectl patch repository porch-test -n default --type=merge -p '{"spec":{"git":{"branch":"develop"}}}' + +# Update directory +kubectl patch repository porch-test -n default --type=merge -p '{"spec":{"git":{"directory":"/packages"}}}' +``` + +{{% alert title="Note" color="primary" %}} +After updating repository configuration, trigger a manual sync to apply changes immediately: + +```bash +porchctl repo sync porch-test --namespace default +``` + +{{% /alert %}} + +**Alternative approach:** + +For significant changes, consider unregistering and re-registering: + +```bash +# Unregister the repository +porchctl repo unregister porch-test --namespace default + +# Re-register with new configuration +porchctl repo register https://github.com/example/porch-test.git \ + --namespace default \ + --name=porch-test \ + --branch=develop \ + --directory=/new-path +``` + +--- diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-registration.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-registration.md new file mode 100644 index 00000000..fc9d3363 --- /dev/null +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-registration.md @@ -0,0 +1,143 @@ +--- +title: "Registering Repositories" +type: docs +weight: 3 +description: "Registering Repositories guide in Porch" +--- + +## Registering Repositories + +Registering a repository connects Porch to your Git storage backend, allowing it to discover and manage packages. You can register repositories with various authentication methods and configuration options. + +### Register a Git Repository + +Register a Git repository with Porch: + +```bash +porchctl repo register https://github.com/example/porch-test.git \ + --namespace default \ + --name=porch-test \ + --description="Blueprint packages" \ + --branch=main +``` + +**What this does:** + +- Registers the Git repository with Porch +- Creates a Repository resource in Kubernetes +- Begins synchronizing packages from the repository + +**Example output:** + +```bash +porch-test created +``` + +**Verify registration:** + +Check that the repository was registered successfully: + +```bash +porchctl repo get porch-test --namespace default +``` + +Look for `READY: True` in the output to confirm the repository is accessible and synchronized. + +```bash +NAME TYPE CONTENT SYNC SCHEDULE DEPLOYMENT READY ADDRESS +porch-test git Package True https://github.com/example-repo/porch-test.git +``` + +**If READY shows False:** + +Inspect the detailed status to see the error message: + +```bash +porchctl repo get porch-test --namespace default -o yaml +``` + +Check the `status.conditions` section for the error details: + +```yaml +status: + conditions: + - type: Ready + status: "False" + reason: Error + message: 'failed to list remote refs: repository not found: Repository not found.' + lastTransitionTime: "2025-11-27T14:32:20Z" +``` + +**Common error messages:** + +- `failed to list remote refs: repository not found` - Repository URL is incorrect or repository doesn't exist +- `failed to resolve credentials: cannot resolve credentials in a secret /: secrets "" not found` - Authentication secret doesn't exist or name is misspelled +- `failed to resolve credentials: resolved credentials are invalid` - Credentials in the secret are invalid or malformed +- `branch "" not found in repository` - Specified branch doesn't exist in the repository +- `repository URL is empty` - Repository URL not specified in configuration +- `target branch is empty` - Branch name not specified in configuration + +--- + +### Register with Authentication + +For private repositories, provide authentication credentials: + +**Using Basic Auth:** + +```bash +porchctl repo register https://github.com/example/private-repo.git \ + --namespace default \ + --name=private-repo \ + --repo-basic-username=myusername \ + --repo-basic-password=mytoken +``` + +**Using Workload Identity (GCP):** + +```bash +porchctl repo register https://github.com/example/private-repo.git \ + --namespace default \ + --name=private-repo \ + --repo-workload-identity +``` + +{{% alert title="Note" color="primary" %}} +For production environments, use secret management solutions (external secret stores, sealed-secrets) rather than embedding credentials in commands. + +See [Authenticating to Remote Git Repositories]({{% relref "/docs/neo-porch/6_configuration_and_deployments/relevant_old_docs/git-authentication-config.md" %}}) for detailed authentication configuration. +{{% /alert %}} + +--- + +### Register with Advanced Options + +Configure additional repository settings: + +```bash +porchctl repo register https://github.com/nephio-project/catalog \ + --namespace default \ + --name=infra \ + --directory=infra \ + --deployment=true \ + --sync-schedule="*/10 * * * *" \ + --description="Infrastructure packages" +``` + +**Common flags:** + +- `--name`: Repository name in Kubernetes (defaults to last segment of URL) +- `--description`: Brief description of the repository +- `--branch`: Git branch to use (defaults to `main`) +- `--directory`: Subdirectory within repository containing packages. Use `/` for repository root, or specify a path like `/blueprints` or `infra/packages`. Leading slash is optional. +- `--deployment`: Mark as deployment repository (packages are deployment-ready) +- `--sync-schedule`: Cron expression for periodic sync (e.g., `*/10 * * * *` for every 10 minutes). Format: `minute hour day month weekday`. +- `--repo-basic-username`: Username for basic authentication +- `--repo-basic-password`: Password/token for basic authentication +- `--repo-workload-identity`: Use workload identity for authentication + +{{% alert title="Note" color="primary" %}} +For complete command syntax and all available flags, see the [Porchctl CLI Guide]({{% relref "/docs/neo-porch/7_cli_api/relevant_old_docs/porchctl-cli-guide.md" %}}). +{{% /alert %}} + +--- diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-synchronization.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-synchronization.md new file mode 100644 index 00000000..a60c0d56 --- /dev/null +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-synchronization.md @@ -0,0 +1,88 @@ +--- +title: "Synchronizing Repositories" +type: docs +weight: 5 +description: "Synchronizing repositories guide in Porch" +--- + +## Repository Synchronization + +Porch periodically synchronizes with registered repositories to discover new packages and updates. You can also trigger manual synchronization when you need immediate updates. + +{{% alert title="Note" color="primary" %}} +**Sync Schedule Format:** Cron expressions follow the format `minute hour day month weekday`. For example, `*/10 * * * *` means "every 10 minutes". +{{% /alert %}} + +### Trigger Manual Sync + +Force an immediate synchronization of a repository: + +```bash +porchctl repo sync porch-test --namespace default +``` + +**What this does:** + +- Schedules a one-time sync (minimum 1-minute delay) +- Updates packages from the repository +- Independent of periodic sync schedule + +**Example output:** + +```bash +Repository porch-test sync scheduled +``` + +--- + +### Sync Multiple Repositories + +Sync several repositories at once: + +```bash +porchctl repo sync repo1 repo2 repo3 --namespace default +``` + +--- + +### Sync All Repositories + +Sync all repositories in a namespace: + +```bash +porchctl repo sync --all --namespace default +``` + +Sync across all namespaces: + +```bash +porchctl repo sync --all --all-namespaces +``` + +--- + +### Schedule Delayed Sync + +Schedule sync with custom delay: + +```bash +# Sync in 5 minutes +porchctl repo sync porch-test --namespace default --run-once 5m + +# Sync in 2 hours 30 minutes +porchctl repo sync porch-test --namespace default --run-once 2h30m + +# Sync at specific time +porchctl repo sync porch-test --namespace default --run-once "2024-01-15T14:30:00Z" +``` + +{{% alert title="Note" color="primary" %}} +**Sync behavior:** + +- Minimum delay is 1 minute from command execution +- Updates `spec.sync.runOnceAt` field in Repository CR +- Independent of existing periodic sync schedule +- Past timestamps are automatically adjusted to minimum delay +{{% /alert %}} + +--- \ No newline at end of file diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-unregistration.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-unregistration.md new file mode 100644 index 00000000..b1fd5b1e --- /dev/null +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-unregistration.md @@ -0,0 +1,43 @@ +--- +title: "Unregistering Repositories" +type: docs +weight: 6 +description: "Unregistering repositories guide in Porch" +--- + +## Unregistering Repositories + +When you no longer need Porch to manage packages from a repository, you can unregister it. This removes Porch's connection to the repository without affecting the underlying Git storage. + +### Unregister a Repository + +Remove a repository from Porch: + +```bash +porchctl repo unregister porch-test --namespace default +``` + +**What this does:** + +- Removes the Repository resource from Kubernetes +- Stops synchronizing packages from the repository +- Removes Porch's cached metadata for the repository +- Does not delete the underlying Git repository or its contents + +{{% alert title="Warning" color="warning" %}} +Unregistering a repository does not delete the underlying Git repository or its contents. It only removes Porch's connection to it. +{{% /alert %}} + +**Example output:** + +```bash +porch-test unregistered +``` + +**What happens to packages:** + +- **Published packages in Git**: Remain in the Git repository and are preserved. If you re-register the same repository later, these packages will reappear when Porch synchronizes. +- **Draft/Proposed packages pushed to Git**: Also remain in Git and will reappear upon re-registration. +- **Unpushed work-in-progress packages**: Cached packages that were never pushed to Git (draft packages being edited) are removed and cannot be recovered. + +--- From 1a22d07543d739169059bf622149c9c00a2d6985 Mon Sep 17 00:00:00 2001 From: Catalin-Stratulat-Ericsson Date: Wed, 3 Dec 2025 10:00:51 +0000 Subject: [PATCH 4/4] amended comments --- .../repository-basic-usage.md | 63 +++++++++---------- .../repository-registration.md | 2 - 2 files changed, 29 insertions(+), 36 deletions(-) diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-basic-usage.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-basic-usage.md index cc438aa6..5d711488 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-basic-usage.md +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-basic-usage.md @@ -122,58 +122,53 @@ status: ### Update Repository Configuration -Updating repository settings is uncommon in practice. The typical workflow is to unregister and re-register the repository with new details. However, if you need to modify an existing repository configuration, you can edit the Kubernetes resource directly. +The typical workflow for changing repository settings is to unregister and re-register the repository with new configuration. This is the recommended approach. {{% alert title="Note" color="primary" %}} -There is no `porchctl repo update` command. Repository updates must be done using kubectl. +There is no `porchctl repo update` command. The standard approach is unregister/reregister. {{% /alert %}} -**Edit a repository:** +**Recommended approach - Unregister and re-register:** ```bash -kubectl edit repository porch-test -n default -``` +# Unregister the repository +porchctl repo unregister porch-test --namespace default -This opens the repository configuration in your default editor. You can modify fields under `spec.git` such as: +# Re-register with new configuration +porchctl repo register https://github.com/example/porch-test.git \ + --namespace default \ + --name=porch-test \ + --branch=develop \ + --directory=/new-path +``` -- `branch`: Change the Git branch -- `directory`: Update the package directory path -- `secretRef.name`: Change authentication credentials -- `deployment`: Toggle deployment repository flag +**Alternative - Direct kubectl editing (NOT RECOMMENDED):** -**Example using kubectl patch:** +While you can edit the repository resource directly with kubectl, this is highly discouraged: ```bash -# Change branch -kubectl patch repository porch-test -n default --type=merge -p '{"spec":{"git":{"branch":"develop"}}}' - -# Update directory -kubectl patch repository porch-test -n default --type=merge -p '{"spec":{"git":{"directory":"/packages"}}}' +kubectl edit repository porch-test -n default ``` -{{% alert title="Note" color="primary" %}} -After updating repository configuration, trigger a manual sync to apply changes immediately: - -```bash -porchctl repo sync porch-test --namespace default -``` +{{% alert title="Warning" color="warning" %}} +Direct editing with kubectl is not recommended because: +- Some values like `url`, `branch`, and `directory` are immutable or not designed to be changed this way +- Changes to authentication secrets (like `secretRef`) are cached by Porch and won't take effect immediately +- Secret changes only apply when authentication fails and Porch refreshes the cached credentials +- This can lead to unpredictable behavior {{% /alert %}} -**Alternative approach:** +**If you must use kubectl editing:** -For significant changes, consider unregistering and re-registering: +Only modify fields that are safe to change, such as: -```bash -# Unregister the repository -porchctl repo unregister porch-test --namespace default +- `secretRef.name`: Change authentication credentials (with caching caveats above) -# Re-register with new configuration -porchctl repo register https://github.com/example/porch-test.git \ - --namespace default \ - --name=porch-test \ - --branch=develop \ - --directory=/new-path -``` +Avoid changing: + +- `url`: Repository URL +- `branch`: Git branch +- `directory`: Package directory path --- diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-registration.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-registration.md index fc9d3363..936c798b 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-registration.md +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-registration.md @@ -5,8 +5,6 @@ weight: 3 description: "Registering Repositories guide in Porch" --- -## Registering Repositories - Registering a repository connects Porch to your Git storage backend, allowing it to discover and manage packages. You can register repositories with various authentication methods and configuration options. ### Register a Git Repository