services.go

Documentation: k8s.io/cri-api/pkg/apis

     1  /*
     2  Copyright 2016 The Kubernetes Authors.
     3  
     4  Licensed under the Apache License, Version 2.0 (the "License");
     5  you may not use this file except in compliance with the License.
     6  You may obtain a copy of the License at
     7  
     8      http://www.apache.org/licenses/LICENSE-2.0
     9  
    10  Unless required by applicable law or agreed to in writing, software
    11  distributed under the License is distributed on an "AS IS" BASIS,
    12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13  See the License for the specific language governing permissions and
    14  limitations under the License.
    15  */
    16  
    17  package cri
    18  
    19  import (
    20  	"context"
    21  	"time"
    22  
    23  	runtimeapi "k8s.io/cri-api/pkg/apis/runtime/v1"
    24  )
    25  
    26  // RuntimeVersioner contains methods for runtime name, version and API version.
    27  type RuntimeVersioner interface {
    28  	// Version returns the runtime name, runtime version and runtime API version
    29  	Version(ctx context.Context, apiVersion string) (*runtimeapi.VersionResponse, error)
    30  }
    31  
    32  // ContainerManager contains methods to manipulate containers managed by a
    33  // container runtime. The methods are thread-safe.
    34  type ContainerManager interface {
    35  	// CreateContainer creates a new container in specified PodSandbox.
    36  	CreateContainer(ctx context.Context, podSandboxID string, config *runtimeapi.ContainerConfig, sandboxConfig *runtimeapi.PodSandboxConfig) (string, error)
    37  	// StartContainer starts the container.
    38  	StartContainer(ctx context.Context, containerID string) error
    39  	// StopContainer stops a running container with a grace period (i.e., timeout).
    40  	StopContainer(ctx context.Context, containerID string, timeout int64) error
    41  	// RemoveContainer removes the container.
    42  	RemoveContainer(ctx context.Context, containerID string) error
    43  	// ListContainers lists all containers by filters.
    44  	ListContainers(ctx context.Context, filter *runtimeapi.ContainerFilter) ([]*runtimeapi.Container, error)
    45  	// ContainerStatus returns the status of the container.
    46  	ContainerStatus(ctx context.Context, containerID string, verbose bool) (*runtimeapi.ContainerStatusResponse, error)
    47  	// UpdateContainerResources updates ContainerConfig of the container synchronously.
    48  	// If runtime fails to transactionally update the requested resources, an error is returned.
    49  	UpdateContainerResources(ctx context.Context, containerID string, resources *runtimeapi.ContainerResources) error
    50  	// ExecSync executes a command in the container, and returns the stdout output.
    51  	// If command exits with a non-zero exit code, an error is returned.
    52  	ExecSync(ctx context.Context, containerID string, cmd []string, timeout time.Duration) (stdout []byte, stderr []byte, err error)
    53  	// Exec prepares a streaming endpoint to execute a command in the container, and returns the address.
    54  	Exec(context.Context, *runtimeapi.ExecRequest) (*runtimeapi.ExecResponse, error)
    55  	// Attach prepares a streaming endpoint to attach to a running container, and returns the address.
    56  	Attach(ctx context.Context, req *runtimeapi.AttachRequest) (*runtimeapi.AttachResponse, error)
    57  	// ReopenContainerLog asks runtime to reopen the stdout/stderr log file
    58  	// for the container. If it returns error, new container log file MUST NOT
    59  	// be created.
    60  	ReopenContainerLog(ctx context.Context, ContainerID string) error
    61  	// CheckpointContainer checkpoints a container
    62  	CheckpointContainer(ctx context.Context, options *runtimeapi.CheckpointContainerRequest) error
    63  	// GetContainerEvents gets container events from the CRI runtime
    64  	GetContainerEvents(containerEventsCh chan *runtimeapi.ContainerEventResponse) error
    65  }
    66  
    67  // PodSandboxManager contains methods for operating on PodSandboxes. The methods
    68  // are thread-safe.
    69  type PodSandboxManager interface {
    70  	// RunPodSandbox creates and starts a pod-level sandbox. Runtimes should ensure
    71  	// the sandbox is in ready state.
    72  	RunPodSandbox(ctx context.Context, config *runtimeapi.PodSandboxConfig, runtimeHandler string) (string, error)
    73  	// StopPodSandbox stops the sandbox. If there are any running containers in the
    74  	// sandbox, they should be force terminated.
    75  	StopPodSandbox(pctx context.Context, odSandboxID string) error
    76  	// RemovePodSandbox removes the sandbox. If there are running containers in the
    77  	// sandbox, they should be forcibly removed.
    78  	RemovePodSandbox(ctx context.Context, podSandboxID string) error
    79  	// PodSandboxStatus returns the Status of the PodSandbox.
    80  	PodSandboxStatus(ctx context.Context, podSandboxID string, verbose bool) (*runtimeapi.PodSandboxStatusResponse, error)
    81  	// ListPodSandbox returns a list of Sandbox.
    82  	ListPodSandbox(ctx context.Context, filter *runtimeapi.PodSandboxFilter) ([]*runtimeapi.PodSandbox, error)
    83  	// PortForward prepares a streaming endpoint to forward ports from a PodSandbox, and returns the address.
    84  	PortForward(context.Context, *runtimeapi.PortForwardRequest) (*runtimeapi.PortForwardResponse, error)
    85  }
    86  
    87  // ContainerStatsManager contains methods for retrieving the container
    88  // statistics.
    89  type ContainerStatsManager interface {
    90  	// ContainerStats returns stats of the container. If the container does not
    91  	// exist, the call returns an error.
    92  	ContainerStats(ctx context.Context, containerID string) (*runtimeapi.ContainerStats, error)
    93  	// ListContainerStats returns stats of all running containers.
    94  	ListContainerStats(ctx context.Context, filter *runtimeapi.ContainerStatsFilter) ([]*runtimeapi.ContainerStats, error)
    95  	// PodSandboxStats returns stats of the pod. If the pod does not
    96  	// exist, the call returns an error.
    97  	PodSandboxStats(ctx context.Context, podSandboxID string) (*runtimeapi.PodSandboxStats, error)
    98  	// ListPodSandboxStats returns stats of all running pods.
    99  	ListPodSandboxStats(ctx context.Context, filter *runtimeapi.PodSandboxStatsFilter) ([]*runtimeapi.PodSandboxStats, error)
   100  	// ListMetricDescriptors gets the descriptors for the metrics that will be returned in ListPodSandboxMetrics.
   101  	ListMetricDescriptors(ctx context.Context) ([]*runtimeapi.MetricDescriptor, error)
   102  	// ListPodSandboxMetrics returns metrics of all running pods.
   103  	ListPodSandboxMetrics(ctx context.Context) ([]*runtimeapi.PodSandboxMetrics, error)
   104  }
   105  
   106  // RuntimeService interface should be implemented by a container runtime.
   107  // The methods should be thread-safe.
   108  type RuntimeService interface {
   109  	RuntimeVersioner
   110  	ContainerManager
   111  	PodSandboxManager
   112  	ContainerStatsManager
   113  
   114  	// UpdateRuntimeConfig updates runtime configuration if specified
   115  	UpdateRuntimeConfig(ctx context.Context, runtimeConfig *runtimeapi.RuntimeConfig) error
   116  	// Status returns the status of the runtime.
   117  	Status(ctx context.Context, verbose bool) (*runtimeapi.StatusResponse, error)
   118  	// RuntimeConfig returns the configuration information of the runtime.
   119  	RuntimeConfig(ctx context.Context) (*runtimeapi.RuntimeConfigResponse, error)
   120  }
   121  
   122  // ImageManagerService interface should be implemented by a container image
   123  // manager.
   124  // The methods should be thread-safe.
   125  type ImageManagerService interface {
   126  	// ListImages lists the existing images.
   127  	ListImages(ctx context.Context, filter *runtimeapi.ImageFilter) ([]*runtimeapi.Image, error)
   128  	// ImageStatus returns the status of the image.
   129  	ImageStatus(ctx context.Context, image *runtimeapi.ImageSpec, verbose bool) (*runtimeapi.ImageStatusResponse, error)
   130  	// PullImage pulls an image with the authentication config.
   131  	PullImage(ctx context.Context, image *runtimeapi.ImageSpec, auth *runtimeapi.AuthConfig, podSandboxConfig *runtimeapi.PodSandboxConfig) (string, error)
   132  	// RemoveImage removes the image.
   133  	RemoveImage(ctx context.Context, image *runtimeapi.ImageSpec) error
   134  	// ImageFsInfo returns information of the filesystem(s) used to store the read-only layers and the writeable layer.
   135  	ImageFsInfo(ctx context.Context) (*runtimeapi.ImageFsInfoResponse, error)
   136  }
   137
View as plain text