kiwiflyer opened a new pull request, #14734:
URL: https://github.com/apache/cloudstack/pull/14734
### Description
This PR lets a NetworkOrchestrator network extension implement VPC private
gateways,
VPC static routes and private gateway ACLs.
`NetworkExtensionElement` implements every other `VpcProvider` method by
building a
JSON payload and handing it to the extension script, but four of them throw
`UnsupportedOperationException`:
```java
createPrivateGateway() -> "Private gateways are not supported by the
network extension element."
deletePrivateGateway() -> "Private gateways are not supported by the
network extension element."
applyStaticRoutes() -> "Static routes are not supported by the
network extension element."
applyACLItemsToPrivateGw() -> "ACL items on private gateways are not
supported by the network extension element."
```
The restriction is at the framework level, so it applies to *every* network
extension
whatever its backend can do. An extension-backed VPC cannot reach parity
with the VPC
virtual router today, and no extension author can fix that on their own side.
**Functional change.** The four methods are wired up the same way as their
neighbours, adding four commands to the script protocol:
| Command | Sent when |
|---|---|
| `create-private-gateway` | a private gateway is created on an
extension-backed VPC |
| `delete-private-gateway` | that gateway is removed |
| `apply-static-routes` | the VPC's static routes change |
| `apply-private-gw-acl` | a network ACL is applied to a private gateway |
An extension that does not implement these verbs is unaffected: the commands
are new,
so nothing dispatches them to a script that has not been updated, and the
existing
behaviour of every other command is unchanged. Before this PR these
operations failed
with `UnsupportedOperationException` regardless of the script, so there is
no case
where previously-working behaviour changes.
Private gateway operations resolve the owning VPC and go through the existing
VPC-level script path, carrying the gateway's id, uuid, address, netmask,
broadcast
URI and derived VLAN alongside the usual VPC fields. `applyStaticRoutes` and
`applyACLItemsToPrivateGw` are full rebuilds that send the complete
non-revoked set on
every call, matching `applyFWRules` and `applyNetworkACLs` rather than the
per-object
style of `add-static-nat`; the backend reconciles instead of tracking deltas.
**One behavioural fix is included.** `addPrivateGatewayToPayload` documents
`gateway_vlan` as conditional but emitted it unconditionally whenever a
broadcast URI
was present. `BroadcastDomainType.getValue()` returns null for a URI whose
scheme it
does not recognise, so a non-VLAN gateway shipped `"gateway_vlan": ""` to
the script.
It is now emitted only when it has a value, which is what the javadoc
already claimed
and what every neighbouring field does.
<!-- Fixes: # -->
### Types of changes
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] Enhancement (improves an existing feature and functionality)
- [ ] Cleanup (Code refactoring and cleanup, that may add test cases)
- [ ] Build/CI
- [ ] Test (unit or integration test code)
### Feature/Enhancement Scale or Bug Severity
#### Feature/Enhancement Scale
- [x] Major
- [ ] Minor
#### Bug Severity
- [ ] BLOCKER
- [ ] Critical
- [ ] Major
- [ ] Minor
- [ ] Trivial
### Screenshots (if appropriate):
n/a
### How Has This Been Tested?
**Unit tests.** `NetworkExtensionElementTest` is new — this 2600-line class
had no unit
test at all before. 26 cases covering the four methods: the payload fields
each one
sends, the VPC and gateway identity the script needs to find the router, the
omit-when-blank branch of every optional field, both failure styles
(`createPrivateGateway`
and `deletePrivateGateway` return false, `applyStaticRoutes` and
`applyACLItemsToPrivateGw`
throw `ResourceUnavailableException`), full serialisation of a static route
and of an ACL
rule, rule ordering by number and routes by CIDR, and a null CIDR passing
through the
route comparator.
`NetworkExtensionElementPayloadContractTest` adds 6 more. It asserts the
keys the
script cannot run without — a transcription of the reference implementation's
`require_arg` calls, with the source named in each test — and writes the
payloads this
class actually produces to `target/extension-payloads/`.
The whole `framework/extensions` module: **377 tests, 0 failures**,
checkstyle clean.
**Against a real OVN.** The payloads captured above were replayed against a
live OVN
24.03 northbound database with `ovn-northd` running, using a reference
extension that
implements the four commands. 21 assertions: the element's
`create-private-gateway`
payload produces a router port carrying its address, its
`apply-static-routes` payload
installs routes that northd resolves into logical flows, its
`apply-network-acl`
payload produces ACLs with rule 10 ahead of rule 20 at the right OVN
priority and the
source CIDRs intact, its `apply-private-gw-acl` payload builds the gateway
ACLs, and
its `delete-private-gateway` payload removes the port. `implement-vpc` is
included,
captured in the state a VPC is first implemented in — no source NAT IP yet.
That replay exists because the unit tests assert what this class *writes*
and an
extension's tests assert what it *reads*, with each side checked against a
fixture
written by the same hand. Both suites would still pass if a key name drifted
between
them. Feeding the real payloads to a real backend is what closes that.
**Not tested:** this has not run on a CloudStack management server driving a
real zone.
The reference extension is not part of this PR.
#### How did you try to break this feature and the system with this change?
Adversarial cases, all now regression tests:
- **No VPC to resolve.** A gateway with a null `vpcId`, and a gateway whose
`vpcId`
points at a VPC that no longer exists. Both must return false and must not
reach the
script. Verified with `verify(..., never())` rather than by return value
alone.
- **Blank and whitespace-only fields.** A gateway with `""`, `null` and `"
"` for its
address, gateway, netmask and broadcast URI, and a null state. Blank is
not the same
as absent: a script testing `-n "$gateway_ip_address"` must not see an
empty string
and configure a port with it. Asserts the keys are *missing*, and that the
mandatory
ones survive.
- **Malformed broadcast URI.** `vlan://bad host` throws `URISyntaxException`
inside
`addPrivateGatewayToPayload`. The call must not abort and the raw value
must still go
out; only the derived VLAN is dropped. A schemeless URI (`untagged`) is
the case that
exposed the empty-string bug above.
- **Null and empty collections.** Null route and rule lists must send an
empty array,
not omit the key — an empty array means "no routes", a missing key means
"unchanged",
and the two are not interchangeable to a reconciling backend.
- **Half-built objects.** A static route with a null CIDR, to prove the sort
comparator
cannot NPE on a route that is mid-construction.
- **Backend failure in both styles**, since the asymmetry is inherited from
`VpcProvider` and is easy to "fix" wrongly in either direction.
- **Mutation testing of the fix.** Reverting the one-line `gateway_vlan`
change makes
`testPrivateGatewayPayloadOmitsVlanWhenBroadcastUriCarriesNone` fail,
confirming the
test is not vacuous.
Two things found while writing these, worth flagging to reviewers:
- Mockito returns `0`, not `null`, for an unstubbed boxed `Integer`. The
first version
of the ACL serialisation test passed for the wrong reason — the
omit-when-null branch
looked taken when it was not. The test now stubs the nulls explicitly and
says why.
- The command name constants are asserted against their string literals.
They are the
wire contract with every deployed script, so a rename should break a test
here rather
than break deployments silently.
**Blast radius.** The four methods previously threw unconditionally, so no
existing
deployment can be executing them. `addPrivateGatewayToPayload`,
`buildStaticRoutesArray`
and `getVpcForPrivateGateway` are new and private. The only pre-existing
code path
touched is the `gateway_vlan` emission described above, which is reachable
only from
the new methods. `buildAclRulesArray` is reused unchanged and is still
covered by the
existing `apply-network-acl` path.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]