cloudflare/resources/load-balancers/pools/pools.d.ts

The official TypeScript library for the Cloudflare API

import * as Core from 'cloudflare/core';
import { APIResource } from 'cloudflare/resource';
import * as PoolsAPI from 'cloudflare/resources/load-balancers/pools/pools';
import * as HealthAPI from 'cloudflare/resources/load-balancers/pools/health';
import * as ReferencesAPI from 'cloudflare/resources/load-balancers/pools/references';
import * as LoadBalancersPoolsAPI from 'cloudflare/resources/user/load-balancers/pools';
import { LoadBalancingPoolsSinglePage } from 'cloudflare/resources/user/load-balancers/pools';
export declare class Pools extends APIResource {
    health: HealthAPI.Health;
    references: ReferencesAPI.References;
    /**
     * Create a new pool.
     */
    create(params: PoolCreateParams, options?: Core.RequestOptions): Core.APIPromise<LoadBalancersPoolsAPI.LoadBalancingPool>;
    /**
     * Modify a configured pool.
     */
    update(poolId: string, params: PoolUpdateParams, options?: Core.RequestOptions): Core.APIPromise<LoadBalancersPoolsAPI.LoadBalancingPool>;
    /**
     * List configured pools.
     */
    list(params: PoolListParams, options?: Core.RequestOptions): Core.PagePromise<LoadBalancingPoolsSinglePage, LoadBalancersPoolsAPI.LoadBalancingPool>;
    /**
     * Delete a configured pool.
     */
    delete(poolId: string, params: PoolDeleteParams, options?: Core.RequestOptions): Core.APIPromise<PoolDeleteResponse>;
    /**
     * Apply changes to an existing pool, overwriting the supplied properties.
     */
    edit(poolId: string, params: PoolEditParams, options?: Core.RequestOptions): Core.APIPromise<LoadBalancersPoolsAPI.LoadBalancingPool>;
    /**
     * Fetch a single configured pool.
     */
    get(poolId: string, params: PoolGetParams, options?: Core.RequestOptions): Core.APIPromise<LoadBalancersPoolsAPI.LoadBalancingPool>;
}
export interface PoolDeleteResponse {
    id?: string;
}
export interface PoolCreateParams {
    /**
     * Path param: Identifier
     */
    account_id: string;
    /**
     * Body param: A short name (tag) for the pool. Only alphanumeric characters,
     * hyphens, and underscores are allowed.
     */
    name: string;
    /**
     * Body param: The list of origins within this pool. Traffic directed at this pool
     * is balanced across all currently healthy origins, provided the pool itself is
     * healthy.
     */
    origins: Array<PoolCreateParams.Origin>;
    /**
     * Body param: A human-readable description of the pool.
     */
    description?: string;
    /**
     * Body param: Whether to enable (the default) or disable this pool. Disabled pools
     * will not receive traffic and are excluded from health checks. Disabling a pool
     * will cause any load balancers using it to failover to the next pool (if any).
     */
    enabled?: boolean;
    /**
     * Body param: The latitude of the data center containing the origins used in this
     * pool in decimal degrees. If this is set, longitude must also be set.
     */
    latitude?: number;
    /**
     * Body param: Configures load shedding policies and percentages for the pool.
     */
    load_shedding?: PoolCreateParams.LoadShedding;
    /**
     * Body param: The longitude of the data center containing the origins used in this
     * pool in decimal degrees. If this is set, latitude must also be set.
     */
    longitude?: number;
    /**
     * Body param: The minimum number of origins that must be healthy for this pool to
     * serve traffic. If the number of healthy origins falls below this number, the
     * pool will be marked unhealthy and will failover to the next available pool.
     */
    minimum_origins?: number;
    /**
     * Body param: The ID of the Monitor to use for checking the health of origins
     * within this pool.
     */
    monitor?: unknown;
    /**
     * Body param: This field is now deprecated. It has been moved to Cloudflare's
     * Centralized Notification service
     * https://developers.cloudflare.com/fundamentals/notifications/. The email address
     * to send health status notifications to. This can be an individual mailbox or a
     * mailing list. Multiple emails can be supplied as a comma delimited list.
     */
    notification_email?: string;
    /**
     * Body param: Filter pool and origin health notifications by resource type or
     * health status. Use null to reset.
     */
    notification_filter?: PoolCreateParams.NotificationFilter | null;
    /**
     * Body param: Configures origin steering for the pool. Controls how origins are
     * selected for new sessions and traffic without session affinity.
     */
    origin_steering?: PoolCreateParams.OriginSteering;
}
export declare namespace PoolCreateParams {
    interface Origin {
        /**
         * The IP address (IPv4 or IPv6) of the origin, or its publicly addressable
         * hostname. Hostnames entered here should resolve directly to the origin, and not
         * be a hostname proxied by Cloudflare. To set an internal/reserved address,
         * virtual_network_id must also be set.
         */
        address?: string;
        /**
         * Whether to enable (the default) this origin within the pool. Disabled origins
         * will not receive traffic and are excluded from health checks. The origin will
         * only be disabled for the current pool.
         */
        enabled?: boolean;
        /**
         * The request header is used to pass additional information with an HTTP request.
         * Currently supported header is 'Host'.
         */
        header?: Origin.Header;
        /**
         * A human-identifiable name for the origin.
         */
        name?: string;
        /**
         * The virtual network subnet ID the origin belongs in. Virtual network must also
         * belong to the account.
         */
        virtual_network_id?: string;
        /**
         * The weight of this origin relative to other origins in the pool. Based on the
         * configured weight the total traffic is distributed among origins within the
         * pool.
         *
         * - `origin_steering.policy="least_outstanding_requests"`: Use weight to scale the
         *   origin's outstanding requests.
         * - `origin_steering.policy="least_connections"`: Use weight to scale the origin's
         *   open connections.
         */
        weight?: number;
    }
    namespace Origin {
        /**
         * The request header is used to pass additional information with an HTTP request.
         * Currently supported header is 'Host'.
         */
        interface Header {
            /**
             * The 'Host' header allows to override the hostname set in the HTTP request.
             * Current support is 1 'Host' header override per origin.
             */
            Host?: Array<string>;
        }
    }
    /**
     * Configures load shedding policies and percentages for the pool.
     */
    interface LoadShedding {
        /**
         * The percent of traffic to shed from the pool, according to the default policy.
         * Applies to new sessions and traffic without session affinity.
         */
        default_percent?: number;
        /**
         * The default policy to use when load shedding. A random policy randomly sheds a
         * given percent of requests. A hash policy computes a hash over the
         * CF-Connecting-IP address and sheds all requests originating from a percent of
         * IPs.
         */
        default_policy?: 'random' | 'hash';
        /**
         * The percent of existing sessions to shed from the pool, according to the session
         * policy.
         */
        session_percent?: number;
        /**
         * Only the hash policy is supported for existing sessions (to avoid exponential
         * decay).
         */
        session_policy?: 'hash';
    }
    /**
     * Filter pool and origin health notifications by resource type or health status.
     * Use null to reset.
     */
    interface NotificationFilter {
        /**
         * Filter options for a particular resource type (pool or origin). Use null to
         * reset.
         */
        origin?: NotificationFilter.Origin | null;
        /**
         * Filter options for a particular resource type (pool or origin). Use null to
         * reset.
         */
        pool?: NotificationFilter.Pool | null;
    }
    namespace NotificationFilter {
        /**
         * Filter options for a particular resource type (pool or origin). Use null to
         * reset.
         */
        interface Origin {
            /**
             * If set true, disable notifications for this type of resource (pool or origin).
             */
            disable?: boolean;
            /**
             * If present, send notifications only for this health status (e.g. false for only
             * DOWN events). Use null to reset (all events).
             */
            healthy?: boolean | null;
        }
        /**
         * Filter options for a particular resource type (pool or origin). Use null to
         * reset.
         */
        interface Pool {
            /**
             * If set true, disable notifications for this type of resource (pool or origin).
             */
            disable?: boolean;
            /**
             * If present, send notifications only for this health status (e.g. false for only
             * DOWN events). Use null to reset (all events).
             */
            healthy?: boolean | null;
        }
    }
    /**
     * Configures origin steering for the pool. Controls how origins are selected for
     * new sessions and traffic without session affinity.
     */
    interface OriginSteering {
        /**
         * The type of origin steering policy to use.
         *
         * - `"random"`: Select an origin randomly.
         * - `"hash"`: Select an origin by computing a hash over the CF-Connecting-IP
         *   address.
         * - `"least_outstanding_requests"`: Select an origin by taking into consideration
         *   origin weights, as well as each origin's number of outstanding requests.
         *   Origins with more pending requests are weighted proportionately less relative
         *   to others.
         * - `"least_connections"`: Select an origin by taking into consideration origin
         *   weights, as well as each origin's number of open connections. Origins with
         *   more open connections are weighted proportionately less relative to others.
         *   Supported for HTTP/1 and HTTP/2 connections.
         */
        policy?: 'random' | 'hash' | 'least_outstanding_requests' | 'least_connections';
    }
}
export interface PoolUpdateParams {
    /**
     * Path param: Identifier
     */
    account_id: string;
    /**
     * Body param: A short name (tag) for the pool. Only alphanumeric characters,
     * hyphens, and underscores are allowed.
     */
    name: string;
    /**
     * Body param: The list of origins within this pool. Traffic directed at this pool
     * is balanced across all currently healthy origins, provided the pool itself is
     * healthy.
     */
    origins: Array<PoolUpdateParams.Origin>;
    /**
     * Body param: A list of regions from which to run health checks. Null means every
     * Cloudflare data center.
     */
    check_regions?: Array<'WNAM' | 'ENAM' | 'WEU' | 'EEU' | 'NSAM' | 'SSAM' | 'OC' | 'ME' | 'NAF' | 'SAF' | 'SAS' | 'SEAS' | 'NEAS' | 'ALL_REGIONS'> | null;
    /**
     * Body param: A human-readable description of the pool.
     */
    description?: string;
    /**
     * Body param: Whether to enable (the default) or disable this pool. Disabled pools
     * will not receive traffic and are excluded from health checks. Disabling a pool
     * will cause any load balancers using it to failover to the next pool (if any).
     */
    enabled?: boolean;
    /**
     * Body param: The latitude of the data center containing the origins used in this
     * pool in decimal degrees. If this is set, longitude must also be set.
     */
    latitude?: number;
    /**
     * Body param: Configures load shedding policies and percentages for the pool.
     */
    load_shedding?: PoolUpdateParams.LoadShedding;
    /**
     * Body param: The longitude of the data center containing the origins used in this
     * pool in decimal degrees. If this is set, latitude must also be set.
     */
    longitude?: number;
    /**
     * Body param: The minimum number of origins that must be healthy for this pool to
     * serve traffic. If the number of healthy origins falls below this number, the
     * pool will be marked unhealthy and will failover to the next available pool.
     */
    minimum_origins?: number;
    /**
     * Body param: The ID of the Monitor to use for checking the health of origins
     * within this pool.
     */
    monitor?: unknown;
    /**
     * Body param: This field is now deprecated. It has been moved to Cloudflare's
     * Centralized Notification service
     * https://developers.cloudflare.com/fundamentals/notifications/. The email address
     * to send health status notifications to. This can be an individual mailbox or a
     * mailing list. Multiple emails can be supplied as a comma delimited list.
     */
    notification_email?: string;
    /**
     * Body param: Filter pool and origin health notifications by resource type or
     * health status. Use null to reset.
     */
    notification_filter?: PoolUpdateParams.NotificationFilter | null;
    /**
     * Body param: Configures origin steering for the pool. Controls how origins are
     * selected for new sessions and traffic without session affinity.
     */
    origin_steering?: PoolUpdateParams.OriginSteering;
}
export declare namespace PoolUpdateParams {
    interface Origin {
        /**
         * The IP address (IPv4 or IPv6) of the origin, or its publicly addressable
         * hostname. Hostnames entered here should resolve directly to the origin, and not
         * be a hostname proxied by Cloudflare. To set an internal/reserved address,
         * virtual_network_id must also be set.
         */
        address?: string;
        /**
         * Whether to enable (the default) this origin within the pool. Disabled origins
         * will not receive traffic and are excluded from health checks. The origin will
         * only be disabled for the current pool.
         */
        enabled?: boolean;
        /**
         * The request header is used to pass additional information with an HTTP request.
         * Currently supported header is 'Host'.
         */
        header?: Origin.Header;
        /**
         * A human-identifiable name for the origin.
         */
        name?: string;
        /**
         * The virtual network subnet ID the origin belongs in. Virtual network must also
         * belong to the account.
         */
        virtual_network_id?: string;
        /**
         * The weight of this origin relative to other origins in the pool. Based on the
         * configured weight the total traffic is distributed among origins within the
         * pool.
         *
         * - `origin_steering.policy="least_outstanding_requests"`: Use weight to scale the
         *   origin's outstanding requests.
         * - `origin_steering.policy="least_connections"`: Use weight to scale the origin's
         *   open connections.
         */
        weight?: number;
    }
    namespace Origin {
        /**
         * The request header is used to pass additional information with an HTTP request.
         * Currently supported header is 'Host'.
         */
        interface Header {
            /**
             * The 'Host' header allows to override the hostname set in the HTTP request.
             * Current support is 1 'Host' header override per origin.
             */
            Host?: Array<string>;
        }
    }
    /**
     * Configures load shedding policies and percentages for the pool.
     */
    interface LoadShedding {
        /**
         * The percent of traffic to shed from the pool, according to the default policy.
         * Applies to new sessions and traffic without session affinity.
         */
        default_percent?: number;
        /**
         * The default policy to use when load shedding. A random policy randomly sheds a
         * given percent of requests. A hash policy computes a hash over the
         * CF-Connecting-IP address and sheds all requests originating from a percent of
         * IPs.
         */
        default_policy?: 'random' | 'hash';
        /**
         * The percent of existing sessions to shed from the pool, according to the session
         * policy.
         */
        session_percent?: number;
        /**
         * Only the hash policy is supported for existing sessions (to avoid exponential
         * decay).
         */
        session_policy?: 'hash';
    }
    /**
     * Filter pool and origin health notifications by resource type or health status.
     * Use null to reset.
     */
    interface NotificationFilter {
        /**
         * Filter options for a particular resource type (pool or origin). Use null to
         * reset.
         */
        origin?: NotificationFilter.Origin | null;
        /**
         * Filter options for a particular resource type (pool or origin). Use null to
         * reset.
         */
        pool?: NotificationFilter.Pool | null;
    }
    namespace NotificationFilter {
        /**
         * Filter options for a particular resource type (pool or origin). Use null to
         * reset.
         */
        interface Origin {
            /**
             * If set true, disable notifications for this type of resource (pool or origin).
             */
            disable?: boolean;
            /**
             * If present, send notifications only for this health status (e.g. false for only
             * DOWN events). Use null to reset (all events).
             */
            healthy?: boolean | null;
        }
        /**
         * Filter options for a particular resource type (pool or origin). Use null to
         * reset.
         */
        interface Pool {
            /**
             * If set true, disable notifications for this type of resource (pool or origin).
             */
            disable?: boolean;
            /**
             * If present, send notifications only for this health status (e.g. false for only
             * DOWN events). Use null to reset (all events).
             */
            healthy?: boolean | null;
        }
    }
    /**
     * Configures origin steering for the pool. Controls how origins are selected for
     * new sessions and traffic without session affinity.
     */
    interface OriginSteering {
        /**
         * The type of origin steering policy to use.
         *
         * - `"random"`: Select an origin randomly.
         * - `"hash"`: Select an origin by computing a hash over the CF-Connecting-IP
         *   address.
         * - `"least_outstanding_requests"`: Select an origin by taking into consideration
         *   origin weights, as well as each origin's number of outstanding requests.
         *   Origins with more pending requests are weighted proportionately less relative
         *   to others.
         * - `"least_connections"`: Select an origin by taking into consideration origin
         *   weights, as well as each origin's number of open connections. Origins with
         *   more open connections are weighted proportionately less relative to others.
         *   Supported for HTTP/1 and HTTP/2 connections.
         */
        policy?: 'random' | 'hash' | 'least_outstanding_requests' | 'least_connections';
    }
}
export interface PoolListParams {
    /**
     * Path param: Identifier
     */
    account_id: string;
    /**
     * Query param: The ID of the Monitor to use for checking the health of origins
     * within this pool.
     */
    monitor?: unknown;
}
export interface PoolDeleteParams {
    /**
     * Identifier
     */
    account_id: string;
}
export interface PoolEditParams {
    /**
     * Path param: Identifier
     */
    account_id: string;
    /**
     * Body param: A list of regions from which to run health checks. Null means every
     * Cloudflare data center.
     */
    check_regions?: Array<'WNAM' | 'ENAM' | 'WEU' | 'EEU' | 'NSAM' | 'SSAM' | 'OC' | 'ME' | 'NAF' | 'SAF' | 'SAS' | 'SEAS' | 'NEAS' | 'ALL_REGIONS'> | null;
    /**
     * Body param: A human-readable description of the pool.
     */
    description?: string;
    /**
     * Body param: Whether to enable (the default) or disable this pool. Disabled pools
     * will not receive traffic and are excluded from health checks. Disabling a pool
     * will cause any load balancers using it to failover to the next pool (if any).
     */
    enabled?: boolean;
    /**
     * Body param: The latitude of the data center containing the origins used in this
     * pool in decimal degrees. If this is set, longitude must also be set.
     */
    latitude?: number;
    /**
     * Body param: Configures load shedding policies and percentages for the pool.
     */
    load_shedding?: PoolEditParams.LoadShedding;
    /**
     * Body param: The longitude of the data center containing the origins used in this
     * pool in decimal degrees. If this is set, latitude must also be set.
     */
    longitude?: number;
    /**
     * Body param: The minimum number of origins that must be healthy for this pool to
     * serve traffic. If the number of healthy origins falls below this number, the
     * pool will be marked unhealthy and will failover to the next available pool.
     */
    minimum_origins?: number;
    /**
     * Body param: The ID of the Monitor to use for checking the health of origins
     * within this pool.
     */
    monitor?: unknown;
    /**
     * Body param: A short name (tag) for the pool. Only alphanumeric characters,
     * hyphens, and underscores are allowed.
     */
    name?: string;
    /**
     * Body param: This field is now deprecated. It has been moved to Cloudflare's
     * Centralized Notification service
     * https://developers.cloudflare.com/fundamentals/notifications/. The email address
     * to send health status notifications to. This can be an individual mailbox or a
     * mailing list. Multiple emails can be supplied as a comma delimited list.
     */
    notification_email?: string;
    /**
     * Body param: Filter pool and origin health notifications by resource type or
     * health status. Use null to reset.
     */
    notification_filter?: PoolEditParams.NotificationFilter | null;
    /**
     * Body param: Configures origin steering for the pool. Controls how origins are
     * selected for new sessions and traffic without session affinity.
     */
    origin_steering?: PoolEditParams.OriginSteering;
    /**
     * Body param: The list of origins within this pool. Traffic directed at this pool
     * is balanced across all currently healthy origins, provided the pool itself is
     * healthy.
     */
    origins?: Array<PoolEditParams.Origin>;
}
export declare namespace PoolEditParams {
    /**
     * Configures load shedding policies and percentages for the pool.
     */
    interface LoadShedding {
        /**
         * The percent of traffic to shed from the pool, according to the default policy.
         * Applies to new sessions and traffic without session affinity.
         */
        default_percent?: number;
        /**
         * The default policy to use when load shedding. A random policy randomly sheds a
         * given percent of requests. A hash policy computes a hash over the
         * CF-Connecting-IP address and sheds all requests originating from a percent of
         * IPs.
         */
        default_policy?: 'random' | 'hash';
        /**
         * The percent of existing sessions to shed from the pool, according to the session
         * policy.
         */
        session_percent?: number;
        /**
         * Only the hash policy is supported for existing sessions (to avoid exponential
         * decay).
         */
        session_policy?: 'hash';
    }
    /**
     * Filter pool and origin health notifications by resource type or health status.
     * Use null to reset.
     */
    interface NotificationFilter {
        /**
         * Filter options for a particular resource type (pool or origin). Use null to
         * reset.
         */
        origin?: NotificationFilter.Origin | null;
        /**
         * Filter options for a particular resource type (pool or origin). Use null to
         * reset.
         */
        pool?: NotificationFilter.Pool | null;
    }
    namespace NotificationFilter {
        /**
         * Filter options for a particular resource type (pool or origin). Use null to
         * reset.
         */
        interface Origin {
            /**
             * If set true, disable notifications for this type of resource (pool or origin).
             */
            disable?: boolean;
            /**
             * If present, send notifications only for this health status (e.g. false for only
             * DOWN events). Use null to reset (all events).
             */
            healthy?: boolean | null;
        }
        /**
         * Filter options for a particular resource type (pool or origin). Use null to
         * reset.
         */
        interface Pool {
            /**
             * If set true, disable notifications for this type of resource (pool or origin).
             */
            disable?: boolean;
            /**
             * If present, send notifications only for this health status (e.g. false for only
             * DOWN events). Use null to reset (all events).
             */
            healthy?: boolean | null;
        }
    }
    /**
     * Configures origin steering for the pool. Controls how origins are selected for
     * new sessions and traffic without session affinity.
     */
    interface OriginSteering {
        /**
         * The type of origin steering policy to use.
         *
         * - `"random"`: Select an origin randomly.
         * - `"hash"`: Select an origin by computing a hash over the CF-Connecting-IP
         *   address.
         * - `"least_outstanding_requests"`: Select an origin by taking into consideration
         *   origin weights, as well as each origin's number of outstanding requests.
         *   Origins with more pending requests are weighted proportionately less relative
         *   to others.
         * - `"least_connections"`: Select an origin by taking into consideration origin
         *   weights, as well as each origin's number of open connections. Origins with
         *   more open connections are weighted proportionately less relative to others.
         *   Supported for HTTP/1 and HTTP/2 connections.
         */
        policy?: 'random' | 'hash' | 'least_outstanding_requests' | 'least_connections';
    }
    interface Origin {
        /**
         * The IP address (IPv4 or IPv6) of the origin, or its publicly addressable
         * hostname. Hostnames entered here should resolve directly to the origin, and not
         * be a hostname proxied by Cloudflare. To set an internal/reserved address,
         * virtual_network_id must also be set.
         */
        address?: string;
        /**
         * Whether to enable (the default) this origin within the pool. Disabled origins
         * will not receive traffic and are excluded from health checks. The origin will
         * only be disabled for the current pool.
         */
        enabled?: boolean;
        /**
         * The request header is used to pass additional information with an HTTP request.
         * Currently supported header is 'Host'.
         */
        header?: Origin.Header;
        /**
         * A human-identifiable name for the origin.
         */
        name?: string;
        /**
         * The virtual network subnet ID the origin belongs in. Virtual network must also
         * belong to the account.
         */
        virtual_network_id?: string;
        /**
         * The weight of this origin relative to other origins in the pool. Based on the
         * configured weight the total traffic is distributed among origins within the
         * pool.
         *
         * - `origin_steering.policy="least_outstanding_requests"`: Use weight to scale the
         *   origin's outstanding requests.
         * - `origin_steering.policy="least_connections"`: Use weight to scale the origin's
         *   open connections.
         */
        weight?: number;
    }
    namespace Origin {
        /**
         * The request header is used to pass additional information with an HTTP request.
         * Currently supported header is 'Host'.
         */
        interface Header {
            /**
             * The 'Host' header allows to override the hostname set in the HTTP request.
             * Current support is 1 'Host' header override per origin.
             */
            Host?: Array<string>;
        }
    }
}
export interface PoolGetParams {
    /**
     * Identifier
     */
    account_id: string;
}
export declare namespace Pools {
    export import PoolDeleteResponse = PoolsAPI.PoolDeleteResponse;
    export import PoolCreateParams = PoolsAPI.PoolCreateParams;
    export import PoolUpdateParams = PoolsAPI.PoolUpdateParams;
    export import PoolListParams = PoolsAPI.PoolListParams;
    export import PoolDeleteParams = PoolsAPI.PoolDeleteParams;
    export import PoolEditParams = PoolsAPI.PoolEditParams;
    export import PoolGetParams = PoolsAPI.PoolGetParams;
    export import Health = HealthAPI.Health;
    export import HealthCreateResponse = HealthAPI.HealthCreateResponse;
    export import HealthGetResponse = HealthAPI.HealthGetResponse;
    export import HealthCreateParams = HealthAPI.HealthCreateParams;
    export import HealthGetParams = HealthAPI.HealthGetParams;
    export import References = ReferencesAPI.References;
    export import ReferenceGetResponse = ReferencesAPI.ReferenceGetResponse;
    export import ReferenceGetParams = ReferencesAPI.ReferenceGetParams;
}
export { LoadBalancingPoolsSinglePage };
//# sourceMappingURL=pools.d.ts.map