REST Resource: namespaces.services

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/master/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 such as "v1alpha1".

kind

string

The kind of resource, in this case "Service".

metadata

object(ObjectMeta)

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

spec

object(ServiceSpec)

Spec holds the desired state of the Service (from the client).

status

object(ServiceStatus)

Status communicates the observed state of the Service (from the controller).

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
{
  "generation": number,

  // Union field spec_type can be only one of the following:
  "runLatest": {
    object(ServiceSpecRunLatest)
  },
  "pinned": {
    object(ServiceSpecPinnedType)
  },
  "release": {
    object(ServiceSpecReleaseType)
  },
  "manual": {
    object(ServiceSpecManualType)
  }
  // End of list of possible types for union field spec_type.
}
Fields
generation
(deprecated)

number

Deprecated and not currently populated by Cloud Run. See metadata.generation instead, which is the sequence number containing the latest generation of the desired state.

Read-only.

Union field spec_type. Reference to one ServiceSpec type. spec_type can be only one of the following:
runLatest

object(ServiceSpecRunLatest)

RunLatest defines a simple Service. It will automatically configure a route that keeps the latest ready revision from the supplied configuration running. +optional

pinned
(deprecated)

object(ServiceSpecPinnedType)

Pins this service to a specific revision name. The revision must be owned by the configuration provided.

Deprecated and not supported by Cloud Run. +optional

release

object(ServiceSpecReleaseType)

Release enables gradual promotion of new revisions by allowing traffic to be split between two revisions. This type replaces the deprecated Pinned type.

Not currently supported by Cloud Run.

manual

object(ServiceSpecManualType)

Manual contains the options for configuring a manual service. See ServiceSpec for more details.

Not currently supported by Cloud Run.

ServiceSpecRunLatest

ServiceSpecRunLatest contains the options for always having a route to the latest configuration. See ServiceSpec for more details.

JSON representation
{
  "configuration": {
    object(ConfigurationSpec)
  }
}
Fields
configuration

object(ConfigurationSpec)

The configuration for this service.

ServiceSpecPinnedType

ServiceSpecPinnedType Pins this service to a specific revision name. The revision must be owned by the configuration provided.

Deprecated and not supported by Cloud Run.

JSON representation
{
  "revisionName": string,
  "configuration": {
    object(ConfigurationSpec)
  }
}
Fields
revisionName

string

The revision name to pin this service to until changed to a different service type.

configuration

object(ConfigurationSpec)

The configuration for this service.

ServiceSpecReleaseType

ServiceSpecReleaseType contains the options for slowly releasing revisions. See ServiceSpec for more details.

Not currently supported by Cloud Run.

JSON representation
{
  "revisions": [
    string
  ],
  "rolloutPercent": number,
  "configuration": {
    object(ConfigurationSpec)
  }
}
Fields
revisions[]

string

Revisions is an ordered list of 1 or 2 revisions. The first is the current revision, and the second is the candidate revision. If a single revision is provided, traffic will be pinned at that revision.

"@latest" is a shortcut for usage that refers to the latest created revision by the configuration.

rolloutPercent

number

RolloutPercent is the percent of traffic that should be sent to the candidate revision, i.e. the 2nd revision in the revisions list. Valid values are between 0 and 99 inclusive.

configuration

object(ConfigurationSpec)

The configuration for this service. All revisions from this service must come from a single configuration.

ServiceSpecManualType

ServiceSpecManualType contains the options for configuring a manual service. See ServiceSpec for more details.

Not currently supported by Cloud Run.

ServiceStatus

The current state of the Service. Output only.

JSON representation
{
  "conditions": [
    {
      object(ServiceCondition)
    }
  ],
  "domain": string,
  "address": {
    object(Addressable)
  },
  "observedGeneration": number,
  "traffic": [
    {
      object(TrafficTarget)
    }
  ],
  "latestReadyRevisionName": string,
  "latestCreatedRevisionName": string
}
Fields
conditions[]

object(ServiceCondition)

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

domain

string

From RouteStatus. Domain holds the top-level domain that will distribute traffic over the provided targets. It generally has the form https://{route-hash}-{project-hash}-{cluster-level-suffix}.a.run.app

address

object(Addressable)

From RouteStatus. Similar to domain, information on where the service is available on HTTP.

observedGeneration

number

ObservedGeneration is the 'Generation' of the Route that was last processed by the controller.

Clients polling for completed reconciliation should poll until observedGeneration = metadata.generation and the Ready condition's status is True or False.

traffic[]

object(TrafficTarget)

From RouteStatus. Traffic 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.

latestReadyRevisionName

string

From ConfigurationStatus. LatestReadyRevisionName holds the name of the latest Revision stamped out from this Service's Configuration that has had its "Ready" condition become "True".

latestCreatedRevisionName

string

From ConfigurationStatus. LatestCreatedRevisionName is the last revision that was created from this Service's Configuration. It might not be ready yet, for that use LatestReadyRevisionName.

ServiceCondition

ServiceCondition defines a readiness condition for a Service.

JSON representation
{
  "type": string,
  "status": string,
  "reason": string,
  "message": string,
  "lastTransitionTime": string
}
Fields
type

string

ServiceConditionType is used to communicate the status of the reconciliation process. See also: https://github.com/knative/serving/blob/master/docs/spec/errors.md#error-conditions-and-reporting

Types include: "Ready", "ConfigurationsReady", and "RoutesReady". "Ready" will be true when the underlying Route and Configuration are ready.

status

string

Status of the condition, one of True, False, Unknown.

reason

string

One-word CamelCase reason for the condition's last transition. +optional

message

string

Human-readable message indicating details about last transition. +optional

lastTransitionTime

string (Timestamp format)

Last time the condition transitioned from one status to another. +optional

A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".

Methods

create

Rpc to create a service.

delete

Rpc to delete a service.

get

Rpc to get information about a service.

list

Rpc to list services.

replaceService

Rpc to replace a service.
Was this page helpful? Let us know how we did:

Send feedback about...