diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..bc2cc64 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,132 @@ +# How to contribute + +NetBox Operator is Apache 2.0 licensed and accepts contributions via GitHub pull requests. + +This document outlines the basics of contributing to NetBox Operator. + +## Running and developing NetBox-Operator locally + +There are several ways of deploying the NetBox operator for development. + +### Running both NetBox Operator and NetBox on a local kind cluster + +Note: This requires Docker BuildKit. + +- Create kind cluster with a NetBox deployment: `make create-kind` +- Deploy the NetBox Operator on the local kind cluster: `make deploy-kind` (In case you're using podman use `CONTAINER_TOOL=podman make deploy-kind`) + +To optionally access the NetBox UI: + +- Port-forward NetBox: `kubectl port-forward deploy/netbox 8080:8080 -n default` +- Open in your favorite browser and log in with the username `admin` and password `admin`, you will be able to access the local NetBox instance running in the kind cluster. + +### Running the NetBox Operator on your machine and NetBox on a local kind cluster + +- Create kind cluster with a NetBox deployment: `make create-kind` +- Port-forward NetBox: `kubectl port-forward deploy/netbox 8080:8080 -n default` +- Open in your favorite browser and log in with the username `admin` and password `admin`, you will be able to access the local NetBox instance running in the kind cluster. +- Open a new terminal window and export the following environment variables: + + ```bash + export NETBOX_HOST="localhost:8080" + export AUTH_TOKEN="0123456789abcdef0123456789abcdef01234567" + export POD_NAMESPACE="default" + export HTTPS_ENABLE="false" + export NETBOX_RESTORATION_HASH_FIELD_NAME="netboxOperatorRestorationHash" + ``` + +- Run the NetBox Operator locally `make install && make run` + +### Running the NetBox Operator on your machine and use an existing NetBox and Kubernetes cluster + +Note: This requires a running NetBox instance that you can use (e.g. ) as well as a kubernetes cluster (can be as simple as `kind create cluster`) + +- Prepare NetBox (based on the demo NetBox instance): + - Open and create any user + - Open and create a token "0123456789abcdef0123456789abcdef01234567" with default settings + - Open and create a custom field called "netboxOperatorRestorationHash" for Object types "IPAM > IP Address" and "IPAM > Prefix" +- Open a new terminal window and export the following environment variables: + + ```bash + export NETBOX_HOST="demo.netbox.dev" + export AUTH_TOKEN="0123456789abcdef0123456789abcdef01234567" + export POD_NAMESPACE="default" + export HTTPS_ENABLE="true" + export NETBOX_RESTORATION_HASH_FIELD_NAME="netboxOperatorRestorationHash" + ``` + +- Run the NetBox Operator locally `make install && make run` + +## Testing NetBox Operator using samples + +In the folder `config/samples/` you can find example manifests to create IpAddress, IpAddressClaim, Prefix and PrefixClaim resources. Apply them to the cluster with `kubectl apply -f ` and use your favorite Kubernetes tools to display. + +Example of assigning a Prefix using PrefixClaim: + +![Figure 2: PrefixClaim example with a NetBox and NetBox Operator instance deployed on the same cluster](docs/prefixclaim-sample-with-netbox-running-in-cluster.drawio.svg) + +1. Apply a PrefixClaim: `kubectl apply -f config/samples/netbox_v1_prefixclaim.yaml` +2. Wait for ready condition: `kubectl wait prefix prefixclaim-sample --for=condition=Ready` +3. List PrefixClaim and Prefix resources: `kubectl get pxc,px` +4. In the prefix status fields you’ll be able to see the netbox URL of the resource. Login with the default `admin`/`admin` credentials to access the NetBox resources. + +Key information can be found in the yaml formatted output of these resources, as well as in the events and Operator logs. + +## To Deploy on the cluster + +### Build and push your image to the location specified by `IMG` + +```sh +make docker-build docker-push IMG=/netbox-operator: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=/netbox-operator:tag +``` + +> **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 directory: + +```sh +kubectl apply -k config/samples/ +``` + +## To Uninstall + +### Delete the instances (CRs) from the cluster + +```sh +kubectl delete -k config/samples/ +``` + +### Delete the APIs(CRDs) from the cluster + +```sh +make uninstall +``` + +### UnDeploy the controller from the cluster + +```sh +make undeploy +``` + +## `make` targets + +Run `make help` for more information on all potential `make` targets + +More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html) diff --git a/README.md b/README.md index 2fb1236..cd7d0e5 100644 --- a/README.md +++ b/README.md @@ -17,9 +17,9 @@ NetBox Operator extends the Kubernetes API by allowing users to manage NetBox re - kind - docker cli -## Running and developing locally +# How to use NetBox Operator -### Running the NetBox Operator and NetBox on a local kind cluster +## Running both NetBox Operator and NetBox on a local kind cluster Note: This requires Docker BuildKit. @@ -31,46 +31,9 @@ To optionally access the NetBox UI: - Port-forward NetBox: `kubectl port-forward deploy/netbox 8080:8080 -n default` - Open in your favorite browser and log in with the username `admin` and password `admin`, you will be able to access the local NetBox instance running in the kind cluster. -### Running the NetBox Operator on your machine and NetBox on a local kind cluster - -- Create kind cluster with a NetBox deployment: `make create-kind` -- Port-forward NetBox: `kubectl port-forward deploy/netbox 8080:8080 -n default` -- Open in your favorite browser and log in with the username `admin` and password `admin`, you will be able to access the local NetBox instance running in the kind cluster. -- Open a new terminal window and export the following environment variables: - - ```bash - export NETBOX_HOST="localhost:8080" - export AUTH_TOKEN="0123456789abcdef0123456789abcdef01234567" - export POD_NAMESPACE="default" - export HTTPS_ENABLE="false" - export NETBOX_RESTORATION_HASH_FIELD_NAME="netboxOperatorRestorationHash" - ``` - -- Run the NetBox Operator locally `make install && make run` - -### Running the NetBox Operator on your machine using an existing NetBox and Kubernetes cluster - -Note: This requires a running NetBox instance that you can use (e.g. ) as well as a kubernetes cluster (can be as simple as `kind create cluster`) - -- Prepare NetBox (based on the demo NetBox instance): - - Open and create any user - - Open and create a token "0123456789abcdef0123456789abcdef01234567" with default settings - - Open and create a custom field called "netboxOperatorRestorationHash" for Object types "IPAM > IP Address" and "IPAM > Prefix" -- Open a new terminal window and export the following environment variables: - - ```bash - export NETBOX_HOST="demo.netbox.dev" - export AUTH_TOKEN="0123456789abcdef0123456789abcdef01234567" - export POD_NAMESPACE="default" - export HTTPS_ENABLE="true" - export NETBOX_RESTORATION_HASH_FIELD_NAME="netboxOperatorRestorationHash" - ``` - -- Run the NetBox Operator locally `make install && make run` - ## Testing NetBox Operator using samples -In the folder `config/samples/` you can find example manifests to create IpAddress, IpAddressClaim, Prefix and PrefixClaim resources. Apply them to the cluster with `kubectl apply -f ` and use your favorite Kubernetes tools to display. +In the folder `config/samples/` you can find example manifests to create IpAddress, IpAddressClaim, Prefix, and PrefixClaim resources. Apply them to the cluster with `kubectl apply -f ` and use your favorite Kubernetes tools to display. Example of assigning a Prefix using PrefixClaim: @@ -83,60 +46,7 @@ Example of assigning a Prefix using PrefixClaim: Key information can be found in the yaml formatted output of these resources, as well as in the events and Operator logs. -## To Deploy on the cluster - -### Build and push your image to the location specified by `IMG` - -```sh -make docker-build docker-push IMG=/netbox-operator: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=/netbox-operator:tag -``` - -> **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 directory: - -```sh -kubectl apply -k config/samples/ -``` - -## To Uninstall - -### Delete the instances (CRs) from the cluster - -```sh -kubectl delete -k config/samples/ -``` - -### Delete the APIs(CRDs) from the cluster - -```sh -make uninstall -``` - -### UnDeploy the controller from the cluster - -```sh -make undeploy -``` - -## Restoration from NetBox +# Restoration from NetBox In the case that the cluster containing the NetBox Custom Resources managed by this NetBox Operator is not backed up (e.g. using Velero), we need to be able to restore some information from NetBox. This includes two mechanisms implemented in this NetBox Operator: @@ -173,11 +83,9 @@ kubectl apply -f https://raw.githubusercontent.com//netbox-operator/ **NOTE**: Run `make help` for more information on all potential `make` targets +We cordially invite collaboration from the community to enhance the quality and functionality of this project. Whether you are addressing bugs, introducing new features, refining documentation, or assisting with items on our to-do list, your contributions are highly valued and greatly appreciated. Please take a look at [Contribution guide] for more details. -More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html) +[Contribution guide]: https://github.com/henrybear327/netbox-operator/CONTRIBUTING.md # License