org.cdk8s.plus31.Service Maven / Gradle / Ivy
package org.cdk8s.plus31;
/**
* An abstract way to expose an application running on a set of Pods as a network service.
*
* With Kubernetes you don't need to modify your application to use an unfamiliar service discovery mechanism.
* Kubernetes gives Pods their own IP addresses and a single DNS name for a set of Pods, and can load-balance across them.
*
* For example, consider a stateless image-processing backend which is running with 3 replicas. Those replicas are fungible—frontends do not care which backend they use.
* While the actual Pods that compose the backend set may change, the frontend clients should not need to be aware of that,
* nor should they need to keep track of the set of backends themselves.
* The Service abstraction enables this decoupling.
*
* If you're able to use Kubernetes APIs for service discovery in your application, you can query the API server for Endpoints,
* that get updated whenever the set of Pods in a Service changes. For non-native applications, Kubernetes offers ways to place a network port
* or load balancer in between your application and the backend Pods.
*/
@javax.annotation.Generated(value = "jsii-pacmak/1.104.0 (build e79254c)", date = "2024-10-12T12:14:17.450Z")
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
@software.amazon.jsii.Jsii(module = org.cdk8s.plus31.$Module.class, fqn = "cdk8s-plus-31.Service")
public class Service extends org.cdk8s.plus31.Resource {
protected Service(final software.amazon.jsii.JsiiObjectRef objRef) {
super(objRef);
}
protected Service(final software.amazon.jsii.JsiiObject.InitializationMode initializationMode) {
super(initializationMode);
}
/**
* @param scope This parameter is required.
* @param id This parameter is required.
* @param props
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public Service(final @org.jetbrains.annotations.NotNull software.constructs.Construct scope, final @org.jetbrains.annotations.NotNull java.lang.String id, final @org.jetbrains.annotations.Nullable org.cdk8s.plus31.ServiceProps props) {
super(software.amazon.jsii.JsiiObject.InitializationMode.JSII);
software.amazon.jsii.JsiiEngine.getInstance().createNewObject(this, new Object[] { java.util.Objects.requireNonNull(scope, "scope is required"), java.util.Objects.requireNonNull(id, "id is required"), props });
}
/**
* @param scope This parameter is required.
* @param id This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public Service(final @org.jetbrains.annotations.NotNull software.constructs.Construct scope, final @org.jetbrains.annotations.NotNull java.lang.String id) {
super(software.amazon.jsii.JsiiObject.InitializationMode.JSII);
software.amazon.jsii.JsiiEngine.getInstance().createNewObject(this, new Object[] { java.util.Objects.requireNonNull(scope, "scope is required"), java.util.Objects.requireNonNull(id, "id is required") });
}
/**
* Configure a port the service will bind to.
*
* This method can be called multiple times.
*
* @param port The port definition. This parameter is required.
* @param options
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public void bind(final @org.jetbrains.annotations.NotNull java.lang.Number port, final @org.jetbrains.annotations.Nullable org.cdk8s.plus31.ServiceBindOptions options) {
software.amazon.jsii.Kernel.call(this, "bind", software.amazon.jsii.NativeType.VOID, new Object[] { java.util.Objects.requireNonNull(port, "port is required"), options });
}
/**
* Configure a port the service will bind to.
*
* This method can be called multiple times.
*
* @param port The port definition. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public void bind(final @org.jetbrains.annotations.NotNull java.lang.Number port) {
software.amazon.jsii.Kernel.call(this, "bind", software.amazon.jsii.NativeType.VOID, new Object[] { java.util.Objects.requireNonNull(port, "port is required") });
}
/**
* Expose a service via an ingress using the specified path.
*
* @return The Ingress resource that was used.
* @param path The path to expose the service under. This parameter is required.
* @param options Additional options.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public @org.jetbrains.annotations.NotNull org.cdk8s.plus31.Ingress exposeViaIngress(final @org.jetbrains.annotations.NotNull java.lang.String path, final @org.jetbrains.annotations.Nullable org.cdk8s.plus31.ExposeServiceViaIngressOptions options) {
return software.amazon.jsii.Kernel.call(this, "exposeViaIngress", software.amazon.jsii.NativeType.forClass(org.cdk8s.plus31.Ingress.class), new Object[] { java.util.Objects.requireNonNull(path, "path is required"), options });
}
/**
* Expose a service via an ingress using the specified path.
*
* @return The Ingress resource that was used.
* @param path The path to expose the service under. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public @org.jetbrains.annotations.NotNull org.cdk8s.plus31.Ingress exposeViaIngress(final @org.jetbrains.annotations.NotNull java.lang.String path) {
return software.amazon.jsii.Kernel.call(this, "exposeViaIngress", software.amazon.jsii.NativeType.forClass(org.cdk8s.plus31.Ingress.class), new Object[] { java.util.Objects.requireNonNull(path, "path is required") });
}
/**
* Require this service to select pods matching the selector.
*
* Note that invoking this method multiple times acts as an AND operator
* on the resulting labels.
*
* @param selector This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public void select(final @org.jetbrains.annotations.NotNull org.cdk8s.plus31.IPodSelector selector) {
software.amazon.jsii.Kernel.call(this, "select", software.amazon.jsii.NativeType.VOID, new Object[] { java.util.Objects.requireNonNull(selector, "selector is required") });
}
/**
* Require this service to select pods with this label.
*
* Note that invoking this method multiple times acts as an AND operator
* on the resulting labels.
*
* @param key This parameter is required.
* @param value This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public void selectLabel(final @org.jetbrains.annotations.NotNull java.lang.String key, final @org.jetbrains.annotations.NotNull java.lang.String value) {
software.amazon.jsii.Kernel.call(this, "selectLabel", software.amazon.jsii.NativeType.VOID, new Object[] { java.util.Objects.requireNonNull(key, "key is required"), java.util.Objects.requireNonNull(value, "value is required") });
}
/**
* The underlying cdk8s API object.
*
* @see base.Resource.apiObject
*/
@Override
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
protected @org.jetbrains.annotations.NotNull org.cdk8s.ApiObject getApiObject() {
return software.amazon.jsii.Kernel.get(this, "apiObject", software.amazon.jsii.NativeType.forClass(org.cdk8s.ApiObject.class));
}
/**
* Return the first port of the service.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public @org.jetbrains.annotations.NotNull java.lang.Number getPort() {
return software.amazon.jsii.Kernel.get(this, "port", software.amazon.jsii.NativeType.forClass(java.lang.Number.class));
}
/**
* Ports for this service.
*
* Use bind() to bind additional service ports.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public @org.jetbrains.annotations.NotNull java.util.List getPorts() {
return java.util.Collections.unmodifiableList(software.amazon.jsii.Kernel.get(this, "ports", software.amazon.jsii.NativeType.listOf(software.amazon.jsii.NativeType.forClass(org.cdk8s.plus31.ServicePort.class))));
}
/**
* The name of a resource type as it appears in the relevant API endpoint.
*/
@Override
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public @org.jetbrains.annotations.NotNull java.lang.String getResourceType() {
return software.amazon.jsii.Kernel.get(this, "resourceType", software.amazon.jsii.NativeType.forClass(java.lang.String.class));
}
/**
* Determines how the Service is exposed.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public @org.jetbrains.annotations.NotNull org.cdk8s.plus31.ServiceType getType() {
return software.amazon.jsii.Kernel.get(this, "type", software.amazon.jsii.NativeType.forClass(org.cdk8s.plus31.ServiceType.class));
}
/**
* The IP address of the service and is usually assigned randomly by the master.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public @org.jetbrains.annotations.Nullable java.lang.String getClusterIP() {
return software.amazon.jsii.Kernel.get(this, "clusterIP", software.amazon.jsii.NativeType.forClass(java.lang.String.class));
}
/**
* The externalName to be used for EXTERNAL_NAME types.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public @org.jetbrains.annotations.Nullable java.lang.String getExternalName() {
return software.amazon.jsii.Kernel.get(this, "externalName", software.amazon.jsii.NativeType.forClass(java.lang.String.class));
}
/**
* A fluent builder for {@link org.cdk8s.plus31.Service}.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public static final class Builder implements software.amazon.jsii.Builder {
/**
* @return a new instance of {@link Builder}.
* @param scope This parameter is required.
* @param id This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public static Builder create(final software.constructs.Construct scope, final java.lang.String id) {
return new Builder(scope, id);
}
private final software.constructs.Construct scope;
private final java.lang.String id;
private org.cdk8s.plus31.ServiceProps.Builder props;
private Builder(final software.constructs.Construct scope, final java.lang.String id) {
this.scope = scope;
this.id = id;
}
/**
* Metadata that all persisted resources must have, which includes all objects users must create.
*
* @return {@code this}
* @param metadata Metadata that all persisted resources must have, which includes all objects users must create. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public Builder metadata(final org.cdk8s.ApiObjectMetadata metadata) {
this.props().metadata(metadata);
return this;
}
/**
* The IP address of the service and is usually assigned randomly by the master.
*
* If an address is specified manually and is not in use by others, it
* will be allocated to the service; otherwise, creation of the service will
* fail. This field can not be changed through updates. Valid values are
* "None", empty string (""), or a valid IP address. "None" can be specified
* for headless services when proxying is not required. Only applies to types
* ClusterIP, NodePort, and LoadBalancer. Ignored if type is ExternalName.
*
* Default: - Automatically assigned.
*
* @return {@code this}
* @see https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies
* @param clusterIp The IP address of the service and is usually assigned randomly by the master. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public Builder clusterIp(final java.lang.String clusterIp) {
this.props().clusterIp(clusterIp);
return this;
}
/**
* A list of IP addresses for which nodes in the cluster will also accept traffic for this service.
*
* These IPs are not managed by Kubernetes. The user
* is responsible for ensuring that traffic arrives at a node with this IP. A
* common example is external load-balancers that are not part of the
* Kubernetes system.
*
* Default: - No external IPs.
*
* @return {@code this}
* @param externalIPs A list of IP addresses for which nodes in the cluster will also accept traffic for this service. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public Builder externalIPs(final java.util.List externalIPs) {
this.props().externalIPs(externalIPs);
return this;
}
/**
* The externalName to be used when ServiceType.EXTERNAL_NAME is set.
*
* Default: - No external name.
*
* @return {@code this}
* @param externalName The externalName to be used when ServiceType.EXTERNAL_NAME is set. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public Builder externalName(final java.lang.String externalName) {
this.props().externalName(externalName);
return this;
}
/**
* A list of CIDR IP addresses, if specified and supported by the platform, will restrict traffic through the cloud-provider load-balancer to the specified client IPs.
*
* More info: https://kubernetes.io/docs/tasks/access-application-cluster/configure-cloud-provider-firewall/
*
* @return {@code this}
* @param loadBalancerSourceRanges A list of CIDR IP addresses, if specified and supported by the platform, will restrict traffic through the cloud-provider load-balancer to the specified client IPs. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public Builder loadBalancerSourceRanges(final java.util.List loadBalancerSourceRanges) {
this.props().loadBalancerSourceRanges(loadBalancerSourceRanges);
return this;
}
/**
* The ports this service binds to.
*
* If the selector of the service is a managed pod / workload,
* its ports will are automatically extracted and used as the default value.
* Otherwise, no ports are bound.
*
* Default: - either the selector ports, or none.
*
* @return {@code this}
* @param ports The ports this service binds to. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public Builder ports(final java.util.List ports) {
this.props().ports(ports);
return this;
}
/**
* The publishNotReadyAddresses indicates that any agent which deals with endpoints for this Service should disregard any indications of ready/not-ready.
*
* More info: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#servicespec-v1-core
*
* Default: - false
*
* @return {@code this}
* @param publishNotReadyAddresses The publishNotReadyAddresses indicates that any agent which deals with endpoints for this Service should disregard any indications of ready/not-ready. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public Builder publishNotReadyAddresses(final java.lang.Boolean publishNotReadyAddresses) {
this.props().publishNotReadyAddresses(publishNotReadyAddresses);
return this;
}
/**
* Which pods should the service select and route to.
*
* You can pass one of the following:
*
*
* - An instance of
Pod or any workload resource (e.g Deployment, StatefulSet, ...)
* - Pods selected by the
Pods.select function. Note that in this case only labels can be specified.
*
*
* Default: - unset, the service is assumed to have an external process managing
* its endpoints, which Kubernetes will not modify.
*
* Example:
*
*
* // select the pods of a specific deployment
* const backend = new kplus.Deployment(this, 'Backend', ...);
* new kplus.Service(this, 'Service', { selector: backend });
* // select all pods labeled with the `tier=backend` label
* const backend = kplus.Pod.labeled({ tier: 'backend' });
* new kplus.Service(this, 'Service', { selector: backend });
*
*
* @return {@code this}
* @param selector Which pods should the service select and route to. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public Builder selector(final org.cdk8s.plus31.IPodSelector selector) {
this.props().selector(selector);
return this;
}
/**
* Determines how the Service is exposed.
*
* More info: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types
*
* Default: ServiceType.ClusterIP
*
* @return {@code this}
* @param type Determines how the Service is exposed. This parameter is required.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public Builder type(final org.cdk8s.plus31.ServiceType type) {
this.props().type(type);
return this;
}
/**
* @return a newly built instance of {@link org.cdk8s.plus31.Service}.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
@Override
public org.cdk8s.plus31.Service build() {
return new org.cdk8s.plus31.Service(
this.scope,
this.id,
this.props != null ? this.props.build() : null
);
}
private org.cdk8s.plus31.ServiceProps.Builder props() {
if (this.props == null) {
this.props = new org.cdk8s.plus31.ServiceProps.Builder();
}
return this.props;
}
}
}