<commit_before># Porch User Guide

This document is focused on using Porch via the `kpt` CLI.

Installation of Porch, including prerequisites, is covered in a
[dedicated document](guides/porch-installation.md).

## Prerequisites

To use Porch, you will need:

* [`kpt`](https://kpt.dev)
* [`gcloud`](https://cloud.google.com/sdk/gcloud) (if running on GKE)
* [`kubectl`](https://kubernetes.io/docs/tasks/tools/#kubectl)

Make sure that your `kubectl` context is set up for `kubectl` to interact with the
correct Kubernetes instance (see
[installation instructions](guides/porch-installation.md) or
the [running-locally](https://github.com/GoogleContainerTools/kpt/blob/main/porch/docs/running-locally.md) guide for details).

To check whether `kubectl` is configured with your Porch cluster (or local instance), run:

```sh
kubectl api-resources | grep porch
```

You should see the following four resourceds listed:

```
repositories                  config.porch.kpt.dev/v1alpha1          true         Repository
packagerevisionresources      porch.kpt.dev/v1alpha1                 true         PackageRevisionResources
packagerevisions              porch.kpt.dev/v1alpha1                 true         PackageRevision
functions                     porch.kpt.dev/v1alpha1                 true         Function
```

## Porch Resources

Porch server manages the following resources:

1. `repositories`: a repository (Git or OCI) can be registered with Porch to support
   discovery or management of KRM configuration packages in those repositories,
   or discovery of KRM functions in those repositories.
2. `packagerevisions`: a specific revision of a KRM configuration package
   managed by Porch in one of the registered repositories. This resource
   represents a _metadata view_ of the KRM configuration package.
3. `packagerevisionresources`: this resource represents the contents of the
   configuration package (KRM resources contained in the package)
4. `functions`: function resource represents a KRM function discovered in a repository
   registered with Porch. Functions are only supported with OCI repositories.

Note that `packagerevisions` and `packagerevisionresources` represent different
_views_ of the same underlying KRM configuration package. `packagerevisions`
represents the package metadata, and `packagerevisionresources` represents the
package content. The matching resources share the same `name` (as well as API
group and version: `porch.kpt.dev/v1alpha1`) and differ in resource kind
(`PackageRevision` and `PackageRevisionResources` respectively).

## Repository Registration

To use Porch with a Git repository, you will need:

* A Git repository for your blueprints.
* A [Personal Access Token](https://github.com/settings/tokens) (when using
  GitHub repository) for Porch to authenticate with the repository.
* Or Basic Auth credentials for Porch to authenticate with the repository.

To use Porch with an OCI repository
([Artifact Registry](https://console.cloud.google.com/artifacts) or
[Google Container Registry](https://cloud.google.com/container-registry)), first
make sure to:
* Enable [workload identity](guides/porch-installation.md#workload-identity) for Porch
* Assign appropriate roles to the Porch workload identity service account
  (`iam.gke.io/gcp-service-account=porch-server@$(GCP_PROJECT_ID).iam.gserviceaccount.com`)
  to have appropriate level of access to your OCI repository.
<commit_msg>Fix guides relative path in a few places (#3175)<commit_after># Porch User Guide

This document is focused on using Porch via the `kpt` CLI.

Installation of Porch, including prerequisites, is covered in a
[dedicated document](./porch-installation.md).

## Prerequisites

To use Porch, you will need:

* [`kpt`](https://kpt.dev)
* [`gcloud`](https://cloud.google.com/sdk/gcloud) (if running on GKE)
* [`kubectl`](https://kubernetes.io/docs/tasks/tools/#kubectl)

Make sure that your `kubectl` context is set up for `kubectl` to interact with the
correct Kubernetes instance (see
[installation instructions](./porch-installation.md) or
the [running-locally](https://github.com/GoogleContainerTools/kpt/blob/main/porch/docs/running-locally.md) guide for details).

To check whether `kubectl` is configured with your Porch cluster (or local instance), run:

```sh
kubectl api-resources | grep porch
```

You should see the following four resourceds listed:

```
repositories                  config.porch.kpt.dev/v1alpha1          true         Repository
packagerevisionresources      porch.kpt.dev/v1alpha1                 true         PackageRevisionResources
packagerevisions              porch.kpt.dev/v1alpha1                 true         PackageRevision
functions                     porch.kpt.dev/v1alpha1                 true         Function
```

## Porch Resources

Porch server manages the following resources:

1. `repositories`: a repository (Git or OCI) can be registered with Porch to support
   discovery or management of KRM configuration packages in those repositories,
   or discovery of KRM functions in those repositories.
2. `packagerevisions`: a specific revision of a KRM configuration package
   managed by Porch in one of the registered repositories. This resource
   represents a _metadata view_ of the KRM configuration package.
3. `packagerevisionresources`: this resource represents the contents of the
   configuration package (KRM resources contained in the package)
4. `functions`: function resource represents a KRM function discovered in a repository
   registered with Porch. Functions are only supported with OCI repositories.

Note that `packagerevisions` and `packagerevisionresources` represent different
_views_ of the same underlying KRM configuration package. `packagerevisions`
represents the package metadata, and `packagerevisionresources` represents the
package content. The matching resources share the same `name` (as well as API
group and version: `porch.kpt.dev/v1alpha1`) and differ in resource kind
(`PackageRevision` and `PackageRevisionResources` respectively).

## Repository Registration

To use Porch with a Git repository, you will need:

* A Git repository for your blueprints.
* A [Personal Access Token](https://github.com/settings/tokens) (when using
  GitHub repository) for Porch to authenticate with the repository.
* Or Basic Auth credentials for Porch to authenticate with the repository.

To use Porch with an OCI repository
([Artifact Registry](https://console.cloud.google.com/artifacts) or
[Google Container Registry](https://cloud.google.com/container-registry)), first
make sure to:
* Enable [workload identity](./porch-installation.md#workload-identity) for Porch
* Assign appropriate roles to the Porch workload identity service account
  (`iam.gke.io/gcp-service-account=porch-server@$(GCP_PROJECT_ID).iam.gserviceaccount.com`)
  to have appropriate level of access to your OCI repository.

{'fraction_non_alphanumeric': 0.07759119861030689, 'fraction_numerical': 0.004632310364794441, 'mean_word_length': 4.202560240963855, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 14, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6623023', 'n_tokens_mistral': 1927, 'n_tokens_neox': 1816, 'n_words': 720}