REST Resource: namespaces.services

Stay organized with collections Save and categorize content based on your preferences.

Resource: Service

Service acts as a top-level container that manages a set of Routes and Configurations which implement a network service. Service exists to provide a singular abstraction which can be access controlled, reasoned about, and which encapsulates software lifecycle decisions such as rollout policy and team resource ownership. Service acts only as an orchestrator of the underlying Routes and Configurations (much as a kubernetes Deployment orchestrates ReplicaSets).

The Service's controller will track the statuses of its owned Configuration and Route, reflecting their statuses and conditions as its own.

See also: https://github.com/knative/serving/blob/main/docs/spec/overview.md#service

JSON representation 
{
  "apiVersion": string,
  "kind": string,
  "metadata": {
    object (ObjectMeta)
  },
  "spec": {
    object (ServiceSpec)
  },
  "status": {
    object (ServiceStatus)
  }
}
Fields
apiVersion

string

The API version for this call. It must be "serving.knative.dev/v1".
kind

string

The kind of resource. It must be "Service".
metadata

object (ObjectMeta)

Metadata associated with this Service, including name, namespace, labels, and annotations.

In Cloud Run, annotations with 'run.googleapis.com/' and 'autoscaling.knative.dev' are restricted, and the accepted annotations will be different depending on the resource type.

The following Cloud Run-specific annotations are accepted in Service.metadata.annotations.

  • run.googleapis.com/binary-authorization-breakglass
  • run.googleapis.com/binary-authorization
  • run.googleapis.com/client-name
  • run.googleapis.com/custom-audiences
  • run.googleapis.com/description
  • run.googleapis.com/gc-traffic-tags
  • run.googleapis.com/ingress

  • run.googleapis.com/ingress sets the ingress settings for the Service. See the ingress settings documentation for details on configuring ingress settings.

  • run.googleapis.com/ingress-status is output-only and contains the currently active ingress settings for the Service. run.googleapis.com/ingress-status may differ from run.googleapis.com/ingress while the system is processing a change to run.googleapis.com/ingress or if the system failed to process a change to run.googleapis.com/ingress. When the system has processed all changes successfully run.googleapis.com/ingress-status and run.googleapis.com/ingress are equal.
spec

object (ServiceSpec)

Holds the desired state of the Service (from the client).
status

object (ServiceStatus)

Communicates the system-controlled state of the Service.

ServiceSpec

ServiceSpec holds the desired state of the Route (from the client), which is used to manipulate the underlying Route and Configuration(s).

JSON representation 
{
  "template": {
    object (RevisionTemplate)
  },
  "traffic": [
    {
      object (TrafficTarget)
    }
  ]
}
Fields
template

object (RevisionTemplate)

Holds the latest specification for the Revision to be stamped out.
traffic[]

object (TrafficTarget)

Specifies how to distribute traffic over a collection of Knative Revisions and Configurations to the Service's main URL.

ServiceStatus

The current state of the Service. Output only.

JSON representation 
{
  "observedGeneration": integer,
  "conditions": [
    {
      object (Condition)
    }
  ],
  "latestReadyRevisionName": string,
  "latestCreatedRevisionName": string,
  "traffic": [
    {
      object (TrafficTarget)
    }
  ],
  "url": string,
  "address": {
    object (Addressable)
  }
}
Fields
observedGeneration

integer

Returns the generation last fully processed by the system. This will only match metadata.generation when reconciliation is complete. Clients polling for completed reconciliation should poll until observedGeneration = metadata.generation and the Ready condition's status is True or False.
conditions[]

object (Condition)

Conditions communicate information about ongoing/complete reconciliation processes that bring the spec inline with the observed state of the world.

Service-specific conditions include:

  • ConfigurationsReady: True when the underlying Configuration is ready.
  • RoutesReady: True when the underlying Route is ready.
  • Ready: True when all underlying resources are ready.
latestReadyRevisionName

string

Name of the latest Revision from this Service's Configuration that has had its Ready condition become True.
latestCreatedRevisionName

string

Name of the last revision that was created from this Service's Configuration. It might not be ready yet, for that use LatestReadyRevisionName.
traffic[]

object (TrafficTarget)

Holds the configured traffic distribution. These entries will always contain RevisionName references. When ConfigurationName appears in the spec, this will hold the LatestReadyRevisionName that we last observed.
url

string

URL that will distribute traffic over the provided traffic targets. It generally has the form https://{route-hash}-{project-hash}-{cluster-level-suffix}.a.run.app
address

object (Addressable)

Similar to url, information on where the service is available on HTTP.

Methods

create

 Creates a new Service.

delete

 Deletes the provided service.

get

 Gets information about a service.

list

 Lists services for the given project and region.

replaceService

 Replaces a service.