Skip to content

Commit f0d4dcd

Browse files
lapentadlapentad
committed
repository doc example
Signed-off-by: lapentafd <[email protected]>
1 parent 97158c9 commit f0d4dcd

File tree

1 file changed

+183
-3
lines changed

1 file changed

+183
-3
lines changed

‎content/en/docs/neo-porch/4_tutorials_&_how-tos/setting-up-repositories.md‎

Lines changed: 183 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,189 @@
22
title: "Setting Up Repositories"
33
type: docs
44
weight: 2
5-
description:
5+
description: "A guide on how to register Git and OCI repositories with Porch using both `porchctl` and `kubectl`."
66
---
77

8-
## Lorem Ipsum
8+
# Setting Up Repositories
99

10-
tutorial in setting up porch repositories and using them
10+
Before Porch can manage packages, you must register the repositories where those packages are stored. This tells Porch where to find package blueprints and where to store deployment packages. Porch supports both Git repositories and OCI registries.
11+
12+
This guide covers the two primary methods for registering a repository with Porch.
13+
14+
## Table of Contents
15+
16+
- [Method 1: Using `porchctl`](#method-1-using-porchctl)
17+
- [Method 2: Using `kubectl`](#method-2-using-kubectl)
18+
19+
## Method 1: Using `porchctl`
20+
21+
The `porchctl` command-line tool provides a straightforward way to register a repository.
22+
23+
### Command Syntax
24+
25+
The basic command for registering a repository is:
26+
27+
```bash
28+
porchctl repo register REPOSITORY [flags]
29+
```
30+
31+
* **`REPOSITORY`**: The URI for the repository.
32+
* For a Git repository, use the standard Git URL (e.g., `http://my-gitea.com/user/repo.git`).
33+
* For an OCI registry, the URI must have the `oci://` prefix (e.g., `oci://us-central1-docker.pkg.dev/my-project/my-repo`).
34+
35+
### Command Flags
36+
37+
The following flags can be used to configure the repository registration:
38+
39+
| Flag | Description |
40+
| ----------------------- | ---------------------------------------------------------------------------------------------------------- |
41+
| `--name` | A unique name for the repository. If not specified, it defaults to the last segment of the repository URL. |
42+
| `--branch` | The branch where finalized packages are committed (Git-only). Defaults to `main`. |
43+
| `--directory` | The directory within the repository where packages are located. Defaults to the repository root (`/`). |
44+
| `--deployment` | If set to `true`, marks the repository as a "deployment" repository, where ready-to-deploy packages reside. |
45+
| `--description` | A human-readable description of the repository. |
46+
| `--repo-basic-username` | The username for basic authentication if the repository is private. |
47+
| `--repo-basic-password` | The password for basic authentication if the repository is private. |
48+
49+
### Example
50+
51+
This example registers a private Git repository hosted on Gitea and configures it as a deployment repository.
52+
53+
```bash
54+
# Register a Git repository with Porch
55+
porchctl repo register http://gitea.gitea:3000/nephio/porch-test.git \
56+
--name=porch-test \
57+
--description="Test repository for Porch packages" \
58+
--branch=main \
59+
--deployment=true \
60+
--repo-basic-username=nephio \
61+
--repo-basic-password=secret
62+
```
63+
64+
## Method 2: Using `kubectl`
65+
66+
Alternatively, you can register a repository by directly applying a `Repository` Custom Resource (CR) to your Kubernetes cluster. This method is ideal for declarative, GitOps-driven workflows.
67+
68+
### Example
69+
70+
This example accomplishes the same goal as the `porchctl` command above. It creates a `Secret` for authentication and a `Repository` CR that references it.
71+
72+
```yaml
73+
# Apply the YAML directly to the cluster
74+
kubectl apply -f - <<EOF
75+
# A dedicated namespace for our Porch resources
76+
apiVersion: v1
77+
kind: Namespace
78+
metadata:
79+
name: porch-demo
80+
---
81+
# A secret to store the Git repository credentials
82+
apiVersion: v1
83+
kind: Secret
84+
metadata:
85+
name: gitea
86+
namespace: porch-demo
87+
type: kubernetes.io/basic-auth
88+
data:
89+
# The username and password must be base64-encoded
90+
# username: nephio -> bmVwaGlv
91+
# password: secret -> c2VjcmV0
92+
username: bmVwaGlv
93+
password: c2VjcmV0
94+
---
95+
# The Repository Custom Resource definition
96+
apiVersion: config.porch.kpt.dev/v1alpha1
97+
kind: Repository
98+
metadata:
99+
name: porch-test
100+
namespace: porch-demo
101+
spec:
102+
description: "Test repository for Porch packages"
103+
# The type of content stored in the repository
104+
content: Package
105+
# Marks this as a deployment repository
106+
deployment: true
107+
# The repository type (git or oci)
108+
type: git
109+
git:
110+
# The URL of the Git repository
111+
repo: http://gitea.gitea:3000/nephio/porch-test.git
112+
# The directory where packages are stored
113+
directory: /
114+
# The branch for published packages
115+
branch: main
116+
# Whether Porch should create the branch if it doesn't exist
117+
createBranch: true
118+
# Reference to the secret containing authentication credentials
119+
secretRef:
120+
name: gitea
121+
EOF
122+
```
123+
124+
### Test Environment Git: Gitea
125+
126+
To create extra repositories via CLI, in this example we create "blueprints" and "deployment" repositories and we gister them with porch.
127+
128+
```bash
129+
GIT_USER="nephio"
130+
GIT_PASS="secret"
131+
GIT_HOST="172.18.255.200:30000" # "localhost:3000" for docker-desktop users in WSL
132+
API_URL="http://$GIT_USER:$GIT_PASS@$GIT_HOST/api/v1/user/repos"
133+
134+
# Define repository names
135+
REPOS=(blueprints deployment)
136+
GIT_ROOT=$(pwd)
137+
# Loop through each repo
138+
for REPO_NAME in "${REPOS[@]}"; do
139+
echo "Creating repo: $REPO_NAME"
140+
141+
# Create the repository via API
142+
curl -v -k -H "Content-Type: application/json" "$API_URL" --data "{\"name\":\"$REPO_NAME\"}"
143+
144+
# Create temp directory and clone repo
145+
TMP_DIR=$(mktemp -d)
146+
cd "$TMP_DIR"
147+
git clone "http://$GIT_USER:$GIT_PASS@$GIT_HOST/$GIT_USER/$REPO_NAME.git"
148+
cd "$REPO_NAME"
149+
150+
# Check if 'main' branch exists
151+
if ! git rev-parse -q --verify refs/remotes/origin/main >/dev/null; then
152+
echo "Add main branch to git repo: $REPO_NAME"
153+
git switch -c main
154+
touch README.md
155+
git add README.md
156+
git config user.name "$GIT_USER"
157+
git commit -m "first commit"
158+
git push -u origin main
159+
else
160+
echo "main branch already exists in git repo: $REPO_NAME"
161+
fi
162+
163+
# Cleanup
164+
cd "$GIT_ROOT"
165+
rm -rf "$TMP_DIR"
166+
167+
168+
kubectl apply -f - <<EOF
169+
apiVersion: config.porch.kpt.dev/v1alpha1
170+
kind: Repository
171+
172+
metadata:
173+
name: $REPO_NAME
174+
namespace: porch-demo
175+
176+
spec:
177+
description: $REPO_NAME packages repo
178+
content: Package
179+
deployment: true
180+
type: git
181+
git:
182+
repo: http://gitea.gitea:3000/nephio/$REPO_NAME.git
183+
directory: /
184+
branch: main
185+
createBranch: true
186+
secretRef:
187+
name: gitea
188+
EOF
189+
done
190+
```

0 commit comments

Comments
 (0)