From aca4df3b15a9c4c9fb1f9432aee4e398a9eb2e8d Mon Sep 17 00:00:00 2001 From: Logan Blyth Date: Thu, 19 Dec 2024 15:58:10 -0500 Subject: [PATCH 1/3] initial draft --- README.md | 216 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 141 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index cda87ec2..ca589c9f 100644 --- a/README.md +++ b/README.md @@ -1,98 +1,164 @@ # fabricator -// TODO(user): Add simple overview of use/purpose -## Description -// TODO(user): An in-depth paragraph about your project and overview of use +Fabricator is the repo that holds the scripts and utilities used to build the +fabric, VLAB, bare metal installers, helm charts, and pods that are used in the +open network fabric. -## Getting Started +## Description -### Prerequisites -- go version v1.22.0+ -- docker version 17.03+. -- kubectl version v1.11.3+. -- Access to a Kubernetes v1.11.3+ cluster. - -### To Deploy on the cluster -**Build and push your image to the location specified by `IMG`:** - -```sh -make docker-build docker-push IMG=/fabricator:tag -``` - -**NOTE:** This image ought to be published in the personal registry you specified. -And it is required to have access to pull the image from the working environment. -Make sure you have the proper permission to the registry if the above commands don’t work. - -**Install the CRDs into the cluster:** - -```sh -make install -``` - -**Deploy the Manager to the cluster with the image specified by `IMG`:** - -```sh -make deploy IMG=/fabricator:tag -``` +The components of this repository are distributed and versioned independently +as OCI compliant artifacts. -> **NOTE**: If you encounter RBAC errors, you may need to grant yourself cluster-admin -privileges or be logged in as admin. -**Create instances of your solution** -You can apply the samples (examples) from the config/sample: +## Local Build Instructions -```sh -kubectl apply -k config/samples/ +### Prerequisites +- go version v1.23.0+ +- docker version 17.03+. (used for logging into ghcr.io) +- [zot v2.1.0](https://zotregistry.dev/v2.1.0/) +- ghcr.io classic token with package **read** permissions +- git + +#### Create a github Classic Token + +1. Log into github.com +1. Click on your icon in the top right corner +1. Click on settings (gear icon) +1. On the left side of the page, scroll down and select "Developer Settings" +1. On the left side click the drop down arrow of "Personal access tokens" +1. Select "Tokens (classic)" +1. On the next page, right of center near the top select "Generate new token" + drop down, then select "Generate new token (classic)" +1. You will be prompted for a TOTP code +1. Name your token according to your needs +1. Select an expiration period of 60-90 days +1. The Scope of the token should be **read** packages, only +1. Click Generate token at the bottom of the page +1. Copy the token down as it will only be visible on this page, it will be used + to configure `zot` in the following step + + +#### Install Zot + +Zot is an OCI package registry. Zot is used on your local system as a +pull-through cache for all artifacts that are not being changed locally as part +of development process. + +[Zot installation +instructions](https://zotregistry.dev/v2.1.0/install-guides/install-guide-linux/#installation) + +The installation instructions above are for the most part distribution +agnostic. Some of the configuration files mentioned in the link are below: + +
+This file: +* creates a registry with data in `/tmp/zot` +* runs a localhost only server on port 30000 +* mirrors everything from the githedgehog github repo + /etc/zot/config.json +```json +{ + "log": { + "level": "debug" + }, + "storage": { + "rootDirectory": "/tmp/zot" + }, + "http": { + "address": "127.0.0.1", + "port": "30000" + }, + "extensions": { + "sync": { + "enable": true, + "credentialsFile": "/etc/zot/creds.json", + "registries": [ + { + "urls": [ + "https://ghcr.io" + ], + "onDemand": true, + "tlsVerify": true, + "content": [ + { + "prefix": "/githedgehog/**", + "destination": "/githedgehog", + "stripPrefix": true + } + ] + } + ] + } + } +} ``` - ->**NOTE**: Ensure that the samples has default values to test it out. - -### To Uninstall -**Delete the instances (CRs) from the cluster:** - -```sh -kubectl delete -k config/samples/ +
+ +
+This file is supplying credentials for zot to read packages using your github +account. +/etc/zot/creds.json +```json + +{ + "ghcr.io": { + "username": "YOUR_USERNAME_HERE", + "password": "READ_ONLY_TOKEN_FROM_GITHUB" + } +} ``` +
-**Delete the APIs(CRDs) from the cluster:** - -```sh -make uninstall +
+/etc/systemd/system/zot.service ``` - -**UnDeploy the controller from the cluster:** - -```sh -make undeploy +[Unit] +Description=OCI Distribution Registry +Documentation=https://zotregistry.dev/ +After=network.target auditd.service local-fs.target + +[Service] +Type=simple +ExecStart=/usr/bin/zot serve /etc/zot/config.json +Restart=on-failure +User=zot +Group=zot +LimitNOFILE=500000 +MemoryHigh=30G +MemoryMax=32G + +[Install] +WantedBy=multi-user.target ``` -## Project Distribution +
-Following are the steps to build the installer and distribute this project to users. -1. Build the installer for the image built and published in the registry: +#### Just push -```sh -make build-installer IMG=/fabricator:tag -``` +The fabricator repo uses a [justfile1] +for building and deploying code. After you have made changes to your code, use +`just oci=http push` to build and push your code. All OCI artifacts will be +versioned using the [version string in tools.just][justfile2] +and will be pushed to the zot registry on the local machine, the new binaries will be created in `./bin/` -NOTE: The makefile target mentioned above generates an 'install.yaml' -file in the dist directory. This file contains all the resources built -with Kustomize, which are necessary to install this project without -its dependencies. +[justfile1](https://github.com/githedgehog/fabricator/blob/21154b09112bdf148957dc75f2ce46d5be7beca0/justfile) +[justfile2](https://github.com/githedgehog/fabricator/blob/21154b09112bdf148957dc75f2ce46d5be7beca0/hack/tools.just#L7) -2. Using the installer +#### hhfab -Users can just run kubectl apply -f to install the project, i.e.: - -```sh -kubectl apply -f https://raw.githubusercontent.com//fabricator//dist/install.yaml -``` +If the code you are changing deals with setting up or managing flatcar, hhfab +will need to be instructed to pull packages from the local zot registry and not +the ghcr. To do this, specify the repo pass the `--registry-repo +127.0.0.1:30000` flag and argument to `hhfab init` along with other flags. +From there continue on with the `hhfab` commands. To get vlab running with +local changes: +* `hhfab init --dev --registry-repo 127.0.0.1` +* `hhfab vlab gen` +* `hhfab vlab up --mode iso` -## Contributing -// TODO(user): Add detailed information on how you would like others to contribute to this project +#### updating pods -**NOTE:** Run `make help` for more information on all potential `make` targets +* (TODO) -More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html) From d699a78fb1351a6cc13c18d61ad2599996c782ca Mon Sep 17 00:00:00 2001 From: Logan Blyth Date: Thu, 19 Dec 2024 16:12:19 -0500 Subject: [PATCH 2/3] more whitespace, less problems Signed-off-by: Logan Blyth --- README.md | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index ca589c9f..3ab0252f 100644 --- a/README.md +++ b/README.md @@ -51,12 +51,15 @@ The installation instructions above are for the most part distribution agnostic. Some of the configuration files mentioned in the link are below:
+ This file: * creates a registry with data in `/tmp/zot` * runs a localhost only server on port 30000 * mirrors everything from the githedgehog github repo + /etc/zot/config.json -```json + +``` { "log": { "level": "debug" @@ -91,14 +94,18 @@ This file: } } } + ```
+ This file is supplying credentials for zot to read packages using your github account. + /etc/zot/creds.json -```json + +``` { "ghcr.io": { @@ -106,11 +113,17 @@ account. "password": "READ_ONLY_TOKEN_FROM_GITHUB" } } + ``` +
+ +A systemd unit file for creating a zot registry. + /etc/systemd/system/zot.service + ``` [Unit] Description=OCI Distribution Registry @@ -133,17 +146,18 @@ WantedBy=multi-user.target
+A `zot` user will need to be created, per the link above. #### Just push -The fabricator repo uses a [justfile1] -for building and deploying code. After you have made changes to your code, use +The fabricator repo uses a [justfile][justfile1] for building and deploying code. After +you have made changes to your code, use `just oci=http push` to build and push your code. All OCI artifacts will be versioned using the [version string in tools.just][justfile2] and will be pushed to the zot registry on the local machine, the new binaries will be created in `./bin/` -[justfile1](https://github.com/githedgehog/fabricator/blob/21154b09112bdf148957dc75f2ce46d5be7beca0/justfile) -[justfile2](https://github.com/githedgehog/fabricator/blob/21154b09112bdf148957dc75f2ce46d5be7beca0/hack/tools.just#L7) +[justfile1]: https://github.com/githedgehog/fabricator/blob/21154b09112bdf148957dc75f2ce46d5be7beca0/justfile +[justfile2]: https://github.com/githedgehog/fabricator/blob/21154b09112bdf148957dc75f2ce46d5be7beca0/hack/tools.just#L7 #### hhfab From af099adfd78d8440d40c2722663b538ea2459a73 Mon Sep 17 00:00:00 2001 From: Logan Blyth Date: Thu, 19 Dec 2024 16:15:06 -0500 Subject: [PATCH 3/3] promote some headings Signed-off-by: Logan Blyth --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 3ab0252f..0a0b8b6d 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ as OCI compliant artifacts. - ghcr.io classic token with package **read** permissions - git -#### Create a github Classic Token +### Create a github Classic Token 1. Log into github.com 1. Click on your icon in the top right corner @@ -38,7 +38,7 @@ as OCI compliant artifacts. to configure `zot` in the following step -#### Install Zot +### Install Zot Zot is an OCI package registry. Zot is used on your local system as a pull-through cache for all artifacts that are not being changed locally as part @@ -148,7 +148,7 @@ WantedBy=multi-user.target A `zot` user will need to be created, per the link above. -#### Just push +### Just push The fabricator repo uses a [justfile][justfile1] for building and deploying code. After you have made changes to your code, use @@ -159,7 +159,7 @@ and will be pushed to the zot registry on the local machine, the new binaries wi [justfile1]: https://github.com/githedgehog/fabricator/blob/21154b09112bdf148957dc75f2ce46d5be7beca0/justfile [justfile2]: https://github.com/githedgehog/fabricator/blob/21154b09112bdf148957dc75f2ce46d5be7beca0/hack/tools.just#L7 -#### hhfab +### hhfab If the code you are changing deals with setting up or managing flatcar, hhfab will need to be instructed to pull packages from the local zot registry and not @@ -171,7 +171,7 @@ local changes: * `hhfab vlab gen` * `hhfab vlab up --mode iso` -#### updating pods +### updating pods * (TODO)