Merge pull request #16 from elgnay/update-readme

update readme & makefile
2026-05-21 16:43:48 +00:00 · 2021-06-25 06:07:35 -04:00
parent b3323dab42 e708709643
commit eb89113408
4 changed files with 206 additions and 48 deletions
--- a/.github/workflows/go-presubmit.yml
+++ b/.github/workflows/go-presubmit.yml
@@ -11,10 +11,10 @@ env:
  # Common versions
  GO_VERSION: '1.16'
  GO_REQUIRED_MIN_VERSION: ''
-  GOPATH: '/home/runner/work/registration-operator/registration-operator/go'
+  GOPATH: '/home/runner/work/placement/placement/go'
 defaults:
  run:
-    working-directory: go/src/open-cluster-management.io/registration-operator
+    working-directory: go/src/open-cluster-management.io/placement

 jobs:
  verify:
@@ -25,7 +25,7 @@ jobs:
        uses: actions/checkout@v2
        with:
          fetch-depth: 1
-          path: go/src/open-cluster-management.io/registration-operator
+          path: go/src/open-cluster-management.io/placement
      - name: install Go
        uses: actions/setup-go@v2
        with:
@@ -41,7 +41,7 @@ jobs:
        uses: actions/checkout@v2
        with:
          fetch-depth: 1
-          path: go/src/open-cluster-management.io/registration-operator
+          path: go/src/open-cluster-management.io/placement
      - name: install Go
        uses: actions/setup-go@v2
        with:
@@ -57,7 +57,7 @@ jobs:
        uses: actions/checkout@v2
        with:
          fetch-depth: 1
-          path: go/src/open-cluster-management.io/registration-operator
+          path: go/src/open-cluster-management.io/placement
      - name: install Go
        uses: actions/setup-go@v2
        with:
@@ -73,7 +73,7 @@ jobs:
        uses: actions/checkout@v2
        with:
          fetch-depth: 1
-          path: go/src/open-cluster-management.io/registration-operator
+          path: go/src/open-cluster-management.io/placement
      - name: install Go
        uses: actions/setup-go@v2
        with:
@@ -89,7 +89,7 @@ jobs:
        uses: actions/checkout@v2
        with:
          fetch-depth: 1
-          path: go/src/open-cluster-management.io/registration-operator
+          path: go/src/open-cluster-management.io/placement
      - name: install Go
        uses: actions/setup-go@v2
        with:
@@ -105,7 +105,7 @@ jobs:
        uses: actions/checkout@v2
        with:
          fetch-depth: 1
-          path: go/src/open-cluster-management.io/registration-operator
+          path: go/src/open-cluster-management.io/placement
      - name: install Go
        uses: actions/setup-go@v2
        with:
@@ -121,7 +121,7 @@ jobs:
          name: cluster1
      - name: Load image on the nodes of the cluster
        run: |
-          kind load docker-image --name=cluster1 quay.io/open-cluster-management/registration-operator:latest
+          kind load docker-image --name=cluster1 quay.io/open-cluster-management/placement:latest
      - name: Run e2e test
        run: |
          make test-e2e
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,51 +1,83 @@
-**Table of Contents**
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*

 - [Contributing guidelines](#contributing-guidelines)
-    - [Terms](#terms)
-    - [Certificate of Origin](#certificate-of-origin)
-    - [DCO Sign Off](#dco-sign-off)
-    - [Code of Conduct](#code-of-conduct)
-    - [Contributing a patch](#contributing-a-patch)
-    - [Issue and pull request management](#issue-and-pull-request-management)
-    - [Pre-check before submitting a PR](#pre-check-before-submitting-a-pr)
+  - [Contributions](#contributions)
+  - [Certificate of Origin](#certificate-of-origin)
+  - [Contributing A Patch](#contributing-a-patch)
+  - [Issue and Pull Request Management](#issue-and-pull-request-management)
+  - [Pre-check before submitting a PR](#pre-check-before-submitting-a-pr)
+  - [Build images](#build-images)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->

 # Contributing guidelines

-## Terms
+## Contributions

 All contributions to the repository must be submitted under the terms of the [Apache Public License 2.0](https://www.apache.org/licenses/LICENSE-2.0).

 ## Certificate of Origin

-By contributing to this project, you agree to the Developer Certificate of Origin (DCO). This document was created by the Linux Kernel community and is a simple statement that you, as a contributor, have the legal right to make the contribution. See the [DCO](https://github.com/open-cluster-management-io/community/blob/main/DCO) file for details.
+By contributing to this project you agree to the Developer Certificate of
+Origin (DCO). This document was created by the Linux Kernel community and is a
+simple statement that you, as a contributor, have the legal right to make the
+contribution. See the [DCO](DCO) file for details.

-## DCO Sign Off
+## Contributing A Patch

-You must sign off your commit to state that you certify the [DCO](https://github.com/open-cluster-management-io/community/blob/main/DCO). To certify your commit for DCO, add a line like the following at the end of your commit message:
+1. Submit an issue describing your proposed change to the repo in question.
+2. The [repo owners](OWNERS) will respond to your issue promptly.
+3. Fork the desired repo, develop and test your code changes.
+4. Submit a pull request.

-```
-Signed-off-by: John Smith <john@example.com>
+## Issue and Pull Request Management
+
+Anyone may comment on issues and submit reviews for pull requests. However, in
+order to be assigned an issue or pull request, you must be a member of the
+[open-cluster-management](https://github.com/open-cluster-management-io) GitHub organization.
+
+Repo maintainers can assign you an issue or pull request by leaving a
+`/assign <your Github ID>` comment on the issue or pull request.
+
+## Pre-check before submitting a PR
+
+After your PR is ready to commit, please run following commands to check your code.
+
+```shell
+make verify
 ```

-This can be done with the `--signoff` option to `git commit`. See the [Git documentation](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt--s) for details. You can also mass sign-off a whole pull request with `git rebase --signoff main`, replacing `main` with the branch you are creating a pull request into.
+Run unit testing
+```shell
+make test-unit
+```

-## Code of Conduct
+Run integration testing
+```shell
+make test-integration
+```

-The Open Cluster Management project has adopted the CNCF Code of Conduct. Refer to our [Community Code of Conduct](https://github.com/open-cluster-management-io/community/blob/main/CODE_OF_CONDUCT.md) for details.
+Run e2e testing.
+```shell
+go install github.com/openshift/imagebuilder/cmd/imagebuilder@v1.2.1

-## Contributing a patch
+export KUBECONFIG=</path/to/kubeconfig>

-1. Submit an issue describing your proposed change to the repository in question. The repository owners will respond to your issue promptly.
-2. Fork the desired repository, then develop and test your code changes.
-3. Submit a pull request.
+make images

-## Issue and pull request management
+kind load docker-image quay.io/open-cluster-management/placement:latest --name {your cluster name}

-Anyone can comment on issues and submit reviews for pull requests. In order to be assigned an issue or pull request, you can leave a `/assign <your Github ID>` comment on the issue or pull request (PR).
+make test-e2e
+```

-## Pre-check before submitting a PR 
-<!-- Customize this template for your repository -->
+## Build images

-Before submitting a PR, please perform the following steps:
+Make sure your code build passed.

- List of steps to perform before submitting a PR.
+```shell
+make images
+```
+
+Now, you can follow the [getting started guide](./README.md#getting-started) to work with this repository.
--- a/7
+++ b/7
@@ -17,7 +17,7 @@ IMAGE_TAG?=latest
 IMAGE_REGISTRY ?= quay.io/open-cluster-management
 IMAGE_NAME?=$(IMAGE_REGISTRY)/$(IMAGE):$(IMAGE_TAG)
 KUBECTL?=kubectl
-KUSTOMIZE?=$(PERMANENT_TMP_GOPATH)/bin/kustomize
+KUSTOMIZE?=$(PWD)/$(PERMANENT_TMP_GOPATH)/bin/kustomize
 KUSTOMIZE_VERSION?=v3.5.4
 KUSTOMIZE_ARCHIVE_NAME?=kustomize_$(KUSTOMIZE_VERSION)_$(GOHOSTOS)_$(GOHOSTARCH).tar.gz
 kustomize_dir:=$(dir $(KUSTOMIZE))
@@ -39,10 +39,13 @@ $(call build-image,$(IMAGE),$(IMAGE_REGISTRY)/$(IMAGE),./Dockerfile,.)

 deploy-hub: ensure-kustomize
 	cp deploy/hub/kustomization.yaml deploy/hub/kustomization.yaml.tmp
-	cd deploy/hub && ../../$(KUSTOMIZE) edit set image quay.io/open-cluster-management/placement:latest=$(IMAGE_NAME)
+	cd deploy/hub && $(KUSTOMIZE) edit set image quay.io/open-cluster-management/placement:latest=$(IMAGE_NAME)
 	$(KUSTOMIZE) build deploy/hub | $(KUBECTL) apply -f -
 	mv deploy/hub/kustomization.yaml.tmp deploy/hub/kustomization.yaml

+undeploy-hub:
+	$(KUSTOMIZE) build deploy/hub | $(KUBECTL) delete --ignore-not-found -f -
+
 build-e2e:
 	go test -c ./test/e2e -mod=vendor

--- a/README.md
+++ b/README.md
@@ -1,19 +1,142 @@
 # Placement

-[![License](https://img.shields.io/:license-apache-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0.html)
-
-## What is the `Placement` repository?
-
 With `Placement`, you can select a set of `ManagedClusters` from the `ManagedClusterSets` bound to the placement namespace.

-Go to the [Contributing guide](CONTRIBUTING.md) to learn how to get involved.
+## Community, discussion, contribution, and support

-## Getting started
+Check the [CONTRIBUTING Doc](CONTRIBUTING.md) for how to contribute to the repo.

-run `make build` to build the binary
+<!--

- Check the [Security guide](SECURITY.md) if you need to report a security issue.
+You can reach the maintainers of this project at:

-## References
+- [#xxx on Slack](https://slack.com/signin?redir=%2Fmessages%2Fxxx)

- The `placement` is part of the `open-cluster-management` community. For more information, visit: [open-cluster-management.io](https://open-cluster-management.io).
+-->
+
+------
+## Getting Started
+
+### Prerequisites
+
+You have at least one running kubernetes cluster;
+
+### Deploy the placement controller
+Set environment variables.
+```sh
+export KUBECONFIG=</path/to/kubeconfig>
+```
+
+Build the docker image to run the placement controller.
+```sh
+make images
+export IMAGE_NAME=<placement_image_name> # export IMAGE_NAME=quay.io/open-cluster-management-io/placement:latest
+```
+
+If your are using kind, load image into kind cluster.
+```sh
+kind load docker-image <placement_image_name> # kind load docker-image quay.io/open-cluster-management-io/placement:latest
+```
+
+And then deploy placement manager on cluster
+```
+make deploy-hub
+```
+
+### What is next
+After a successful deployment, check on the cluster and see the placement controller has been deployed.
+```
+kubectl -n open-cluster-management-hub get pods
+NAME                                                  READY   STATUS    RESTARTS   AGE
+cluster-manager-placement-controller-cf9bbd6c-x9dnd   1/1     Running   0          2m16s
+```
+
+Create a clusterset.yaml as shown in this example:
+
+```yaml
+apiVersion: cluster.open-cluster-management.io/v1alpha1
+kind: ManagedClusterSet
+metadata:
+  name: clusterset1
+```
+
+Apply the yaml file to the cluster to create a `ManagedClusterSet`.
+```
+kubectl apply -f clusterset.yaml
+```
+
+Create a cluster.yaml:
+
+```yaml
+apiVersion: cluster.open-cluster-management.io/v1
+kind: ManagedCluster
+metadata:
+  name: cluster1
+  labels:
+    cluster.open-cluster-management.io/clusterset: clusterset1
+    vendor: OpenShift
+spec:
+  hubAcceptsClient: true
+```
+
+Apply the yaml file to create a cluster and assign it to clusterset `clusterset1`.
+```
+kubectl apply -f cluster.yaml
+```
+
+And then create a binding.yaml:
+
+```yaml
+apiVersion: cluster.open-cluster-management.io/v1alpha1
+kind: ManagedClusterSetBinding
+metadata:
+  name: clusterset1
+  namespace: default
+spec:
+  clusterSet: clusterset1
+```
+
+Apply the yaml file to bind the `ManagedClusterSet` to the default namespace.
+```
+kubectl apply -f binding.yaml
+```
+
+Now create a placement.yaml:
+```yaml
+apiVersion: cluster.open-cluster-management.io/v1alpha1
+kind: Placement
+metadata:
+  name: placement1
+  namespace: default
+spec:
+  predicates:
+    - requiredClusterSelector:
+        labelSelector:
+          matchLabels:
+            vendor: OpenShift
+```
+Apply the yaml file to create the placement.
+
+```
+kubectl apply -f placement.yaml
+```
+
+Check the 'PlacementDecision'created for this placement. It contains all selected clusters in status.
+```
+kubectl get placementdecisions
+NAME                    AGE
+placement1-decision-1   14s
+```
+
+### Clean up
+Undeploy placement controller from the cluster.
+```
+make undeploy-hub
+```
+
+<!--
+## XXX References
+
+If you have any further question about xxx, please refer to
+[XXX help documentation](docs/xxx_help.md) for further information.
+-->