Skip to content

Commit 567de2b

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #2706 from pottekkat/doc/improve-readme/1
doc: gwctl - improve readme, add Makefile
2 parents 40a26ea + 66c7d79 commit 567de2b

File tree

2 files changed

+140
-80
lines changed

2 files changed

+140
-80
lines changed

‎gwctl/Makefile

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Copyright 2024 The Kubernetes Authors.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
deps:
16+
@echo "Installing dependencies..."
17+
@go mod tidy
18+
@go mod vendor
19+
20+
build: deps
21+
@echo "Building gwctl..."
22+
@go build -o bin/gwctl cmd/main.go

‎gwctl/README.md

Lines changed: 118 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -1,138 +1,176 @@
11
# gwctl
22

3-
gwctl is a tool that improves the usability of the Gateway API by providing a better way to view and manage policies ([GEP-713](https://gateway-api.sigs.k8s.io/geps/gep-713)). The aim is to make it available as a standalone binary, a kubectl plugin, and a library.
3+
gwctl is a tool that improves the usability of the Gateway API by providing a better way to view and manage policies ([GEP-713](https://gateway-api.sigs.k8s.io/geps/gep-713)). The aim is to make it available as a standalone binary, a [kubectl plugin](https://gateway-api.sigs.k8s.io/geps/gep-713/#kubectl-plugin-or-command-line-tool), and a library.
44

55
gwctl allows you to view all Gateway API policy types that are present in a cluster, as well as all "policy bindings" in a namespace (or across all namespaces). It also shows you the attached policies when you view any Gateway resource (like HTTPRoute, Gateway, GatewayClass, etc.)
66

7-
gwctl uses the `gateway.networking.k8s.io/policy=true` label to identify Policy CRDs (https://gateway-api.sigs.k8s.io/geps/gep-713/#kubectl-plugin)
8-
9-
Please note that gwctl is still considered an [experimental feature of Gateway API](https://gateway-api.sigs.k8s.io/concepts/versioning/#release-channels-eg-experimental-standard). While we iterate on the early stages of this tool, bugs and incompatible changes will be more likely.
7+
gwctl uses the `gateway.networking.k8s.io/policy=true` label to identify Policy CRDs.
108

9+
> [!NOTE]
10+
> gwctl is still considered an [experimental feature of the Gateway API](https://gateway-api.sigs.k8s.io/concepts/versioning/#release-channels-eg-experimental-standard). While we iterate on the early stages of this tool, bugs and incompatible changes will be more likely.
1111
1212
In the future, gwctl may be able to read status from the policy resource to determine if it has been applied correctly.
1313

14-
## Try it out!
14+
## Installation
1515

16-
```bash
17-
# Clone the gwctl repository
18-
git clone https://github.com/kubernetes-sigs/gateway-api.git
16+
1. Before you install gwctl, ensure that your system meets the following requirements:
17+
1. Install Git: Make sure Git is installed on your system to clone the project repository.
18+
2. Install Go. Make sure the Go language is installed on your system. You can download it from the [official website](https://golang.org/dl/) and follow the installation instructions.
1919

20-
# Go to the gwctl directory
21-
cd gateway-api/gwctl
20+
2. Clone the project repository:
21+
22+
```bash
23+
git clone https://github.com/kubernetes-sigs/gateway-api.git && cd gateway-api/gwctl
24+
```
2225

23-
# Ensure vendor dependencies
24-
go mod tidy
25-
go mod vendor
26+
3. Build the project:
27+
28+
```bash
29+
make build
30+
```
2631

27-
# Build the gwctl binary
28-
go build -o bin/gwctl cmd/main.go
32+
4. Add binary to `PATH`:
33+
34+
```bash
35+
export PATH="./bin:${PATH}"
36+
```
2937

30-
# Add binary to PATH
31-
export PATH=./bin:${PATH}
38+
5. Run gwctl:
39+
40+
```shell
41+
gwctl help
42+
```
3243

33-
# Start using!
34-
gwctl help
35-
```
44+
## Usage
45+
46+
The examples below demonstrate how gwctl can be used.
3647

37-
## Examples
38-
Here are some examples of how gwctl can be used:
48+
List all policies in the cluster. This will also show the resource they bind to:
3949

4050
```bash
41-
# List all policies in the cluster. This will also give the resource they bind to.
4251
gwctl get policies -A
52+
```
4353

44-
# List all available policy types
45-
gwctl get policycrds
46-
47-
# Describe all HTTPRoutes in namespace ns2
48-
gwctl describe httproutes -n ns2
54+
```
55+
POLICYNAME POLICYKIND TARGETNAME TARGETKIND
56+
timeout-policy-on-gatewayclass TimeoutPolicy foo-com-external-gateway-class GatewayClass
57+
timeout-policy-on-namespace TimeoutPolicy default Namespace
58+
health-check-1 HealthCheckPolicy gateway-1 Gateway
59+
retry-policy-1 RetryOnPolicy gateway-1 Gateway
60+
retry-policy-2 RetryOnPolicy httproute-2 HTTPRoute
61+
tls-min-version-policy-1 TLSMinimumVersionPolicy httproute-1 HTTPRoute
62+
tls-min-version-policy-2 TLSMinimumVersionPolicy gateway-2 Gateway
63+
```
4964

50-
# Describe a single HTTPRoute in default namespace
51-
gwctl describe httproutes demo-httproute-1
65+
List all available policy types:
5266

53-
# Describe all Gateways across all namespaces.
54-
gwctl describe gateways -A
67+
```bash
68+
gwctl get policycrds
69+
```
5570

56-
# Describe a single GatewayClass
57-
gwctl describe gatewayclasses foo-com-external-gateway-class
71+
```
72+
NAME GROUP KIND POLICY TYPE SCOPE
73+
backendtlspolicies.gateway.networking.k8s.io gateway.networking.k8s.io BackendTLSPolicy Direct Namespaced
5874
```
5975

60-
Here are some commands with their sample output:
76+
Describe all HTTPRoutes in namespace `prod`:
77+
6178
```bash
62-
❯ gwctl get policies -A
63-
POLICYNAME POLICYKIND TARGETNAME TARGETKIND
64-
demo-timeout-policy-on-gatewayclass TimeoutPolicy foo-com-external-gateway-class GatewayClass
65-
demo-timeout-policy-on-namespace TimeoutPolicy default Namespace
66-
demo-health-check-1 HealthCheckPolicy demo-gateway-1 Gateway
67-
demo-retry-policy-1 RetryOnPolicy demo-gateway-1 Gateway
68-
demo-retry-policy-2 RetryOnPolicy demo-httproute-2 HTTPRoute
69-
demo-tls-min-version-policy-1 TLSMinimumVersionPolicy demo-httproute-1 HTTPRoute
70-
demo-tls-min-version-policy-2 TLSMinimumVersionPolicy demo-gateway-2 Gateway
71-
72-
❯ gwctl describe httproutes -n ns2
73-
Name: demo-httproute-3
74-
Namespace: ns2
79+
gwctl describe httproutes -n prod
80+
```
81+
82+
```
83+
Name: httproute-3
84+
Namespace: prod
7585
Hostnames:
7686
- example.com
7787
ParentRefs:
7888
- group: gateway.networking.k8s.io
7989
kind: Gateway
80-
name: demo-gateway-2
90+
name: gateway-2
8191
EffectivePolicies:
82-
ns2/demo-gateway-2:
92+
prod/gateway-2:
8393
TLSMinimumVersionPolicy.baz.com:
8494
default:
85-
sampleField: hello
95+
sampleField: sample
8696
8797
88-
Name: demo-httproute-4
89-
Namespace: ns2
98+
Name: httproute-4
99+
Namespace: prod
90100
Hostnames:
91101
- demo.com
92102
ParentRefs:
93103
- group: gateway.networking.k8s.io
94104
kind: Gateway
95-
name: demo-gateway-1
105+
name: gateway-1
96106
namespace: default
97107
EffectivePolicies:
98-
default/demo-gateway-1:
108+
default/gateway-1:
99109
HealthCheckPolicy.foo.com:
100110
default:
101111
sampleField: hello
102112
RetryOnPolicy.foo.com:
103113
default:
104-
sampleField: hello
114+
sampleField: sample
105115
TimeoutPolicy.bar.com:
106116
timeout1: parent
107117
timeout2: child
108118
timeout3: parent
109119
timeout4: child
120+
```
110121

111-
❯ gwctl describe backends service/demo-svc
112-
Kind: Service
113-
Name: demo-svc
114-
Namespace: default
122+
Describe a single HTTPRoute in default namespace:
123+
124+
```shell
125+
gwctl describe httproutes httproute-1
126+
```
127+
128+
```
129+
Name: httproute-1
130+
Namespace: dev
131+
Hostnames:
132+
- example.com
133+
ParentRefs:
134+
- group: gateway.networking.k8s.io
135+
kind: Gateway
136+
name: gateway-1
115137
EffectivePolicies:
116-
default/demo-gateway-1:
117-
HealthCheckPolicy.foo.com:
118-
default:
119-
sampleField: hello
120-
RetryOnPolicy.foo.com:
121-
default:
122-
sampleField: hello
123-
TLSMinimumVersionPolicy.baz.com: {}
124-
TimeoutPolicy.bar.com:
125-
timeout1: parent
126-
timeout2: child
127-
timeout3: parent
128-
timeout4: child
129-
ns2/demo-gateway-2:
138+
dev/gateway-2:
130139
TLSMinimumVersionPolicy.baz.com:
131140
default:
132-
sampleField: hello
133-
TimeoutPolicy.bar.com:
134-
timeout1: child
135-
timeout2: child
136-
timeout3: child
137-
timeout4: child
141+
sampleField: sample
138142
```
143+
144+
Describe all Gateways across all namespaces:
145+
146+
```shell
147+
gwctl describe gateways -A
148+
```
149+
150+
```
151+
Name: gateway-1
152+
Namespace: default
153+
GatewayClass: foo-com-external-gateway-class
154+
155+
Name: gateway-2
156+
Namespace: prod
157+
GatewayClass: foo-com-external-gateway-class
158+
159+
Name: gateway-3
160+
Namespace: dev
161+
GatewayClass: foo-com-external-gateway-class
162+
```
163+
164+
> [!TIP]
165+
> You can use the `--help` or the `-h` flag for a usage guide for any subcommand.
166+
167+
## Get Involved
168+
169+
This project will be discussed in the same Slack channel and community meetings as the rest of the Gateway API subproject. For more information, refer to the [Gateway API Community](https://gateway-api.sigs.k8s.io/contributing/) page.
170+
171+
### Code of conduct
172+
173+
Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](code-of-conduct.md).
174+
175+
[owners]: https://git.k8s.io/community/contributors/guide/owners.md
176+
[Creative Commons 4.0]: https://git.k8s.io/website/LICENSE

0 commit comments

Comments
 (0)