# CRI Network API

## Background

We are proposing making network configuration part of the CRI. That way, runtimes could expose network configuration management to the orchestrator / end-user.

## Overview

1. Network configuration is part of the CRI API. There are CRUD methods for managing network configuration
2. CRI-compliant runtimes maintain CNI (or other potential plugin systems) configurations in response to CRI calls. The implementation is not defined.
3. (optional) There may be more than one network configuration.

### Kubernetes integration

This prototype **does not** include a corresponding Kubernetes API type for network configuration. Configuring a network within a runtime could be accomplished by:
1. The administrator adding a CNI configuration file out-of-band
2. A system daemon making requests to the CRI socket:
- A specific vendor taking direct control of the network
- A daemon that watches NetworkAttachmentDefinition objects
-
3. The kubelet consuming CNI configuration via
- a possible NetworkClass API type
- files on disk
- etc...

## API & Types

A first proposal is as follows:

service RuntimeService {
    rpc SetPodNetwork(SetPodNetworkRequest) returns (CreatePodNetworkResponse) {}
    
    rpc RemovePodNetwork(RemovePodNetworkRequest) returns RemovePodNetworkResponse) {}
    
    rpc ListPodNetwork(ListPodNetworkRequest) returns (ListPodNetworkResponse) {}
}

message NetworkMetadata {
    string name = 1;
    string namespace = 2;
    string uid = 3;
    uint32 generation = 4;
}

message CNIv1PluginConfig {
    string type = 1;
    
    // capabilities is the set of parameters this plugin
    // understands.
    repeated string capabilities = 2;
    
    map<string, string> parameters = 3;
}

message CNIv1Config {
    string cni_version = 1;
    
    string network_name = 2;
    
    bool disable_check = 3;
    
    repeated CNIPluginConfig = 4;

}

message IPRange {
    string cidr = 1;
}

enum NetworkType {
    CNIv1 = 0;
}

// The NetworkConfig mesage represents a desired network configuration
// that a CRI-compliant runtime is able to manage.
message NetworkConfig {
    NetworkMetadata metadata = 1;
    
    // the IP range is optional
    repeated IPRange ip_ranges = 2;
    
    NetworkType network_type = 3;
    
    CNIv1Config cniv1_config = 4;
}

message SetPodNetworkRequest {
    NetworkConfig config = 1;
}


message NetworkStatus {
    // if true, the network is ready to handle
    // sandbox creation and deletion requests
    bool sandbox_management = 1;
    
    // if true, existing sandboxes have connectivity
    bool connectivity = 2;
}

message PodNetworkResponse
    NetworkConfig config = 1;
    
    NetworkStatus status = 2;
}

message ListPodNetworkResponse {
    repeated PodNetworkResponse = 1;
}

message PodSandboxNetworkConfig {
    string interface_name = 1;
    
    string network_name = 2;
    
    map<string, string> parameters = 3;

}

// This is the existing PodSandboxConfig object as present
// in the CRI -- see https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto#L388
message PodSandboxConfig {
    // (existing fields elided...)
    
    // List of pod network attachments
    repeated PodSandboxNetworkConfig

}

// PodIP represents an ip of a Pod
message PodIP{
    // an ip is a string representation of an IPv4 or an IPv6
    string ip = 1; // (existing)
    
    string network_name = 2;
}

### Defaulting and initialization

We assume the presence of a default network, and PodSandboxes with no networks requested will receive this network with an interface named `eth0` - to preserve existing behavior.

Container runtimes currently read their CNI configuration from a folder on disk. Accordingly, if such a configuration is detected, it should be automatically created and, thus, be included in a ListPodNetworkResponse.

### Backwards compatibility

Right now, network management is internal to the runtime. The convention is to return a NotReady RuntimeCondition if CNI configuration is not present.

In order to support backwards compatibility, we should consider an empty ListPodNetworks response, but a fully ready RuntimeCondition as an acceptable response for managing sandboxes.

Further, as discussed above, container runtimes should preserve the existing behavior of watching a folder on disk for CNI configuration files. This network would have the reserved name `_fallback`.