Tutorial: Setting Up a Net Peering Between a Net and an OKS Project (Beta)

This feature is currently in beta. For more information about beta services, see the Glossary and our General Terms and Conditions of Sale.

In this tutorial, you learn how to peer one of your project to one of your Nets.

You can peer a project to a Net to enable secure communication between clusters and external resources located across different accounts and Nets.

With OKS, peering is managed directly from within a cluster using custom resources. While the request is initiated from a cluster, the Net is peered with the project the cluster belongs to, which in turn grants access to all clusters within that project.

You can either set up the peering:

  • From the cluster to the Net, using a peering request custom resource.

  • From the Net to the cluster, using a peering acceptance custom resource.

It is not possible to create a Net peering between a cluster and a Net that have overlapping CIDR blocks. The CIDR block used when creating the Net must be different from that of the project containing the cluster from which you want to initiate the peering. For more information, see Getting Information About a Cluster.

It is possible to peer your cluster to a Net from a different account, the logic of this tutorial stays the same.

Setting Up a Net Peering From Your Cluster to Your Net

Before you begin:

  1. Create the custom resource for the peering request. This resource is a YAML file in which you must add the following pieces of information:

    • accepterNetId: the ID of the Net you created.

    • accepterOwnerId: the ID of your Outscale account.

      peering-request.yaml
      apiVersion: oks.dev/v1beta
kind: NetPeeringRequest
metadata:
  name: peering-request
spec:
  accepterNetId: ID_OF_YOUR_NET
  accepterOwnerId: "ID_YOUR_OUTSCALE_ACCOUNT"

  2. Apply the peering request file to your cluster using the following command:

    Request sample
    oks-cli cluster --project-name "NAME_OF_PROJECT" --cluster-name NAME_OF_CLUSTER kubectl apply -f ~/PATH/peering-request.yaml
    Result sample
    netpeeringrequest.oks.dev/peering-request created

  3. Run the following command to obtain the Net peering ID needed to accept the peering request:

    Request sample
    oks-cli cluster --project-name "NAME_OF_PROJECT" --cluster-name NAME_OF_CLUSTER kubectl get npr
    Result sample
    NAME              SOURCE NET ID   ACCEPTER NET ID   NET PEERING ID   STATE NAME           STATE MESSAGE                        EXPIRATION DATE
peering-request   ID_OF_YOUR_CLUSTER    ID_OF_YOUR_NET     ID_OF_NET_PEERING     pending-acceptance   Pending acceptance by ID_YOUR_OUTSCALE_ACCOUNT

  4. Accept the peering request on the Net side, using OSC CLI.

    Request sample
    osc-cli api AcceptNetPeering --NetPeeringId "ID_OF_NET_PEERING"

  5. You can check that the peering has been set up correctly with the following command:

    Request sample
    oks-cli cluster --project-name "project-1" --cluster-name cluster-1 kubectl get npeer
    Result sample
    NAME           SOURCE NET ID   ACCEPTER NET ID   NET PEERING ID   STATE NAME   STATE MESSAGE   EXPIRATION DATE
pcx-1a2b3c4d   ID_OF_YOUR_CLUSTER    ID_OF_YOUR_NET     ID_OF_NET_PEERING     active       Active          2025-08-04T11:28:46.000Z

    You can also check that the peering has been set up correctly using Cockpit and OSC CLI. For more information, see Getting Information About Your Net Peerings.

A Net peering never expires. You can disregard the expiration date appearing in the result of the OKS CLI command.

Setting Up a Net Peering From Your Net to Your Cluster

Before you begin:

  • Create a Net. This action can be done using Cockpit or OSC CLI. For more information, see Creating a Net.

  • Create a cluster to be peered with your Net. For more information, see Creating a Cluster.

  • Create a node pool and get information about that node pool. For more information see Listing Your Node Pools > Listing Node Pools Using kubectl. This enable you to gather the following pieces of information regarding the cluster you created:

    • the ID of your OKS account (oks.account-id),

    • the ID of your OKS network (oks.network_id).

  1. Create a Net peering with SourceNetId the ID of the Net you previously created, AccepterNetId the ID of your OKS network, which represents the ID of your cluster, and AccepterOwnerId the ID of your OKS account. For more information, see Creating a Net Peering.

    Request sample
    osc-cli api CreateNetPeering --profile exp-dev-010 --SourceNetId "ID_OF_YOUR_NET" --AccepterNetId "ID_OF_YOUR_CLUSTER" --AccepterOwnerId '"ID_OF_OKS_ACCOUNT"'
    Result sample
    {
    "ResponseContext": {
        "RequestId": "b99e373a-4abe-4249-bd37-08dbfe9caa1c"
    },
    "NetPeering": {
        "Tags": [],
        "State": {
            "Name": "pending-acceptance",
            "Message": "Pending acceptance by ID_OF_OKS_ACCOUNT"
        },
        "AccepterNet": {
            "NetId": "ID_OF_YOUR_CLUSTER",
            "IpRange": "10.50.0.0/16",
            "AccountId": "ID_OF_OKS_ACCOUNT"
        },
        "SourceNet": {
            "NetId": "ID_OF_YOUR_NET",
            "IpRange": "192.168.0.0/16",
            "AccountId": "ID_YOUR_OUTSCALE_ACCOUNT"
        },
        "NetPeeringId": "ID_OF_NET_PEERING"
    }
}

  2. Create the custom resource for the peering acceptance. This resource is a YAML file in which you must add the ID of the previously obtained Net peering.

    peering-acceptance.yaml
    apiVersion: oks.dev/v1beta
kind: NetPeeringAcceptance
metadata:
  name: peering-acceptance
spec:
  netPeeringId: ID_OF_NET_PEERING

  3. Apply the peering acceptance file to your cluster:

    Request sample
    oks-cli cluster --project-name "project-1" --cluster-name cluster-1 kubectl apply -f ~/PATH/peering-acceptance.yaml
    Result sample
    netpeeringacceptance.oks.dev/peering-acceptance created

  4. You can check that the peering has been set up correctly with the following command:

    Request sample
    oks-cli cluster --project-name "projet1" --cluster-name cluster1 kubectl get npeer
    Result sample
    NAME           SOURCE NET ID   ACCEPTER NET ID   NET PEERING ID   STATE NAME   STATE MESSAGE   EXPIRATION DATE
pcx-1a2b3c4d   ID_OF_YOUR_NET    ID_OF_YOUR_CLUSTER     ID_OF_NET_PEERING     active       Active          2025-08-04T11:28:46.000Z

    You can also check that the peering has been set up correctly using Cockpit. For more information, see Getting Information About Your Net Peerings.

A Net peering never expires. You can disregard the expiration date appearing in the result of the OKS CLI command.

Deleting the Net Peering

You can delete the Net peering established between your cluster and your Net using the kubectl delete npeer command, followed by the ID of the Net peering:

Request sample
oks-cli cluster --project-name "projet1" --cluster-name cluster1 kubectl delete npeer ID_OF_NET_PEERING
Result sample
netpeering.oks.dev "ID_OF_NET_PEERING" deleted

Related Pages

Export to PDF