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/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..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/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/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..5d711488 --- /dev/null +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-basic-usage.md @@ -0,0 +1,174 @@ +--- +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 + +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. The standard approach is unregister/reregister. +{{% /alert %}} + +**Recommended approach - Unregister and re-register:** + +```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 +``` + +**Alternative - Direct kubectl editing (NOT RECOMMENDED):** + +While you can edit the repository resource directly with kubectl, this is highly discouraged: + +```bash +kubectl edit repository porch-test -n 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 %}} + +**If you must use kubectl editing:** + +Only modify fields that are safe to change, such as: + +- `secretRef.name`: Change authentication credentials (with caching caveats above) + +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 new file mode 100644 index 00000000..936c798b --- /dev/null +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-registration.md @@ -0,0 +1,141 @@ +--- +title: "Registering Repositories" +type: docs +weight: 3 +description: "Registering Repositories guide in Porch" +--- + +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. + +---