You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**oci-pivot-controller is a Kubernetes controller that gives your cluster a stable floating public IP on OCI — and automatically moves it to a healthy node if the current one goes down.**
8
9
9
-
### Prerequisites
10
-
- go version v1.24.6+
11
-
- docker version 17.03+.
12
-
- kubectl version v1.11.3+.
13
-
- Access to a Kubernetes v1.11.3+ cluster.
10
+
In plain terms: you create a `PivotIP` resource pointing at a Service, and the controller reserves a real OCI public IP address and wires it up so traffic reaches your app. If the node holding that IP becomes unhealthy, the controller detects it, picks a better node, and re-routes traffic — without you doing anything. The IP address never changes.
14
11
15
-
### To Deploy on the cluster
16
-
**Build and push your image to the location specified by `IMG`:**
12
+
It works entirely through OCI's native networking (secondary private IPs + reserved public IPs). No load balancer, no cloud provider integration, no CNI changes required.
17
13
18
-
```sh
19
-
make docker-build docker-push IMG=<some-registry>/oci-pivot-controller:tag
20
-
```
14
+
## What It Manages
21
15
22
-
**NOTE:** This image ought to be published in the personal registry you specified.
23
-
And it is required to have access to pull the image from the working environment.
24
-
Make sure you have the proper permission to the registry if the above commands don’t work.
16
+
-`PivotIP`: assigns and maintains a floating OCI reserved public IP for a Kubernetes Service
25
17
26
-
**Install the CRDs into the cluster:**
18
+
## How It Works
27
19
28
-
```sh
29
-
make install
30
-
```
20
+
1. You create a `PivotIP` pointing at a Service.
21
+
2. The controller picks the healthiest node (fewest existing assignments, must be Ready).
22
+
3. It creates a secondary private IP on that node's VNIC and attaches a reserved OCI public IP to it.
23
+
4. It sets `Service.spec.externalIPs` so the node intercepts and routes inbound traffic to your pods.
24
+
5. When the node becomes unhealthy, the controller moves the secondary private IP to a new node and reassigns the public IP — the address stays the same.
31
25
32
-
**Deploy the Manager to the cluster with the image specified by `IMG`:**
26
+
## Prerequisites
33
27
34
-
```sh
35
-
make deploy IMG=<some-registry>/oci-pivot-controller:tag
36
-
```
28
+
- Kubernetes cluster running on OCI Compute instances (Ampere A1 or x86)
29
+
- OCI IAM policy granting the controller permission to manage private and public IPs (see below)
30
+
-`helm` (recommended) or `kubectl`
37
31
38
-
> **NOTE**: If you encounter RBAC errors, you may need to grant yourself cluster-admin
39
-
privileges or be logged in as admin.
32
+
### Required OCI IAM Policy
40
33
41
-
**Create instances of your solution**
42
-
You can apply the samples (examples) from the config/sample:
34
+
The controller uses [instance principal authentication](https://docs.oracle.com/en-us/iaas/Content/Identity/Tasks/callingservicesfrominstances.htm) — no API key needed. Add this policy to the dynamic group that contains your cluster nodes:
43
35
44
-
```sh
45
-
kubectl apply -k config/samples/
36
+
```
37
+
Allow dynamic-group <your-node-group> to manage private-ips in compartment <your-compartment>
38
+
Allow dynamic-group <your-node-group> to manage public-ips in compartment <your-compartment>
46
39
```
47
40
48
-
>**NOTE**: Ensure that the samples has default values to test it out.
Following the options to release and provide this solution to the users.
70
+
## First Floating IP in 5 Minutes
72
71
73
-
### By providing a bundle with all YAML files
74
-
75
-
1. Build the installer for the image built and published in the registry:
72
+
Create a Service and a PivotIP in the `default` namespace:
76
73
77
74
```sh
78
-
make build-installer IMG=<some-registry>/oci-pivot-controller:tag
75
+
kubectl apply -f - <<'EOF'
76
+
apiVersion: v1
77
+
kind: Service
78
+
metadata:
79
+
name: my-app
80
+
namespace: default
81
+
spec:
82
+
selector:
83
+
app: my-app
84
+
ports:
85
+
- port: 80
86
+
targetPort: 8080
87
+
---
88
+
apiVersion: pivot.oci.io/v1alpha1
89
+
kind: PivotIP
90
+
metadata:
91
+
name: my-app-ip
92
+
namespace: default
93
+
spec:
94
+
serviceRef:
95
+
name: my-app
96
+
EOF
79
97
```
80
98
81
-
**NOTE:** The makefile target mentioned above generates an 'install.yaml'
82
-
file in the dist directory. This file contains all the resources built
83
-
with Kustomize, which are necessary to install this project without its
84
-
dependencies.
85
-
86
-
2. Using the installer
87
-
88
-
Users can just run 'kubectl apply -f <URLforYAMLBUNDLE>' to install
89
-
the project, i.e.:
99
+
Check status:
90
100
91
101
```sh
92
-
kubectl apply -f https://raw.githubusercontent.com/<org>/oci-pivot-controller/<tag or branch>/dist/install.yaml
93
-
```
94
-
95
-
### By providing a Helm Chart
102
+
kubectl get pivotip -n default
103
+
# NAME PUBLIC IP NODE SERVICE AGE
104
+
# my-app-ip 1.2.3.4 node-worker1 my-app 30s
96
105
97
-
1. Build the chart using the optional helm plugin
106
+
kubectl describe pivotip my-app-ip -n default
107
+
```
98
108
99
-
```sh
100
-
kubebuilder edit --plugins=helm/v2-alpha
109
+
The `PUBLIC IP` column shows the OCI reserved public IP. Traffic to that address on port 80 reaches your app pods via the elected node.
110
+
111
+
## PivotIP Reference
112
+
113
+
```yaml
114
+
apiVersion: pivot.oci.io/v1alpha1
115
+
kind: PivotIP
116
+
metadata:
117
+
name: my-app-ip
118
+
namespace: default
119
+
spec:
120
+
# Service in the same namespace to attach the floating IP to. Required.
121
+
serviceRef:
122
+
name: my-app
123
+
124
+
# Only nodes matching these labels are eligible to hold the IP.
125
+
# If omitted, all Ready nodes are eligible.
126
+
nodeSelector:
127
+
topology.kubernetes.io/zone: uk-london-1-ad-1
128
+
129
+
# OCI compartment OCID for creating IP resources.
130
+
# Defaults to the --compartment-id flag set on the controller.
131
+
compartmentId: ocid1.compartment.oc1..example
101
132
```
102
133
103
-
2. See that a chart was generated under 'dist/chart', and users
104
-
can obtain this solution from there.
134
+
## Examples
135
+
136
+
See [`examples/`](examples/) for complete real-world use cases:
105
137
106
-
**NOTE:** If you change the project, you need to update the Helm Chart
107
-
using the same command above to sync the latest changes. Furthermore,
108
-
if you create webhooks, you need to use the above command with
109
-
the '--force' flag and manually ensure that any custom configuration
110
-
previously added to 'dist/chart/values.yaml' or 'dist/chart/manager/manager.yaml'
111
-
is manually re-applied afterwards.
138
+
- [`examples/nginx-floating-ip/`](examples/nginx-floating-ip/) — Nginx exposed with a floating public IP, zone-pinned to a specific availability domain
112
139
113
140
## Contributing
114
-
// TODO(user): Add detailed information on how you would like others to contribute to this project
115
141
116
-
**NOTE:**Run `make help` for more information on all potential `make`targets
142
+
Pull requests welcome. Run `make help` for all available targets.
117
143
118
-
More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)
144
+
```sh
145
+
make test # run unit + integration tests
146
+
make lint # lint
147
+
make build # compile
148
+
```
119
149
120
150
## License
121
151
@@ -132,4 +162,3 @@ distributed under the License is distributed on an "AS IS" BASIS,
132
162
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
133
163
See the License for the specific language governing permissions and
0 commit comments