upcoming: [UIE-10426] - Add new endpoints, types and Queries for Reserved IPs

packages/api-v4/.changeset/pr-13517-upcoming-features-1774273074612.md

@@ -0,0 +1,5 @@
+---
+"@linode/api-v4": Upcoming Features
+---
+
+Reserved IPs: Added new API endpoints ([#13517](https://github.com/linode/manager/pull/13517))

packages/api-v4/src/networking/networking.ts

@@ -1,6 +1,7 @@
 import {
   allocateIPSchema,
   assignAddressesSchema,
+  reserveIPSchema,
   shareAddressesSchema,
   updateIPSchema,
 } from '@linode/validation/lib/networking.schema';
@@ -14,14 +15,16 @@ import Request, {
   setXFilter,
 } from '../request';
 
-import type { Filter, ResourcePage as Page, Params } from '../types';
+import type { Filter, ResourcePage as Page, Params, PriceType } from '../types';
 import type {
+  AllocateIPPayload,
   CreateIPv6RangePayload,
   IPAddress,
   IPAssignmentPayload,
   IPRange,
   IPRangeInformation,
   IPSharingPayload,
+  ReserveIPPayload,
 } from './types';
 
 /**
@@ -52,16 +55,24 @@ export const getIP = (address: string) =>
  * Sets RDNS on an IP Address. Forward DNS must already be set up for reverse
  * DNS to be applied. If you set the RDNS to null for public IPv4 addresses,
  * it will be reset to the default members.linode.com RDNS value.
+ * Also setting “reserved” field to true converts an Ephemeral IP to an Reserved IP.
+ * setting “reserved” field set to false converts a Reserved IP to an Ephemeral IP.
+ * An Ephemeral IP is an IP that’s assigned to a Linode but not reserved.
  *
  * @param address { string } The address to operate on.
  * @param rdns { string } The reverse DNS assigned to this address. For public
  * IPv4 addresses, this will be set to a default value provided by Linode if not
  * explicitly set.
+ * @param reserved { boolean } Whether to reserve the IP address.
  */
-export const updateIP = (address: string, rdns: null | string = null) =>
+export const updateIP = (
+  address: string,
+  rdns: null | string = null,
+  reserved?: boolean,
+) =>
   Request<IPAddress>(
     setURL(`${API_ROOT}/networking/ips/${encodeURIComponent(address)}`),
-    setData({ rdns }, updateIPSchema),
+    setData({ rdns, reserved }, updateIPSchema),
     setMethod('PUT'),
   );
 
@@ -77,8 +88,11 @@ export const updateIP = (address: string, rdns: null | string = null) =>
  * address.
  * @param payload.linode_id { number } The ID of a Linode you you have access to
  *  that this address will be allocated to.
+ * @param payload.reserved { boolean } Whether to reserve the IP address.
+ * @param payload.region { string } The ID of the Region in which this address * will be allocated.
+ * Required when reserving an IP address, not required when allocating an ephemeral IP address.
  */
-export const allocateIp = (payload: any) =>
+export const allocateIp = (payload: AllocateIPPayload) =>
   Request<IPAddress>(
     setURL(`${API_ROOT}/networking/ips/`),
     setData(payload, allocateIPSchema),
@@ -194,3 +208,93 @@ export const createIPv6Range = (payload: CreateIPv6RangePayload) => {
     setData(payload),
   );
 };
+
+// Reserve IP queries
+/**
+ * getReservedIps
+ *
+ * Returns a paginated list of all Reserved IP addresses on this account.
+ */
+export const getReservedIPs = (params?: Params, filters?: Filter) =>
+  Request<Page<IPAddress>>(
+    setMethod('GET'),
+    setParams(params),
+    setXFilter(filters),
+    setURL(`${BETA_API_ROOT}/networking/reserved/ips`),
+  );
+
+/**
+ * Returns information about a single Reserved IP Address on your Account.
+ *
+ * @param address { string } The address to operate on.
+ */
+export const getReservedIP = (address: string) =>
+  Request<IPAddress>(
+    setURL(
+      `${BETA_API_ROOT}/networking/reserved/ips/${encodeURIComponent(address)}`,
+    ),
+    setMethod('GET'),
+  );
+
+/**
+ * Tags associated with the reserved IP can be updated.
+ * The tags associated with the reserved IP will be completely replaced with the values specified in the request body,
+ * rather than just adding additional tags to what’s already there
+ *
+ * @param address { string } The address to operate on.
+ * @param tags { string[] | null } The tags to associate with this reserved IP. If null, all tags will be removed.
+ */
+export const updateReservedIP = (
+  address: string,
+  tags: null | string[] = null,
+) =>
+  Request<IPAddress>(
+    setURL(
+      `${BETA_API_ROOT}/networking/reserved/ips/${encodeURIComponent(address)}`,
+    ),
+    setData({ tags }),
+    setMethod('PUT'),
+  );
+
+/**
+ * Makes one of the IP address available in the provided region as reserved.
+ * Only IPv4 addresses may be reserved through this endpoint.
+ *
+ * @param payload { Object }
+ * @param payload.region { string } The ID of the Region in which these
+ * assignments are to take place. All IPs and Linodes must exist in this Region.
+ * @param payload.tags { string[] } A list of tags to associate with this reserved IP.
+ */
+export const reserveIP = (payload: ReserveIPPayload) =>
+  Request<IPAddress>(
+    setURL(`${BETA_API_ROOT}/networking/reserved/ips`),
+    setData(payload, reserveIPSchema),
+    setMethod('POST'),
+  );
+
+/**
+ * unReserveIP
+ *
+ * Unreserves an IP address, making it available for general use.
+ * Any Tag associations will be removed when the IP address is un-reserved via this endpoint.
+ *
+ */
+export const unReserveIP = (ipAddress: string) =>
+  Request<object>(
+    setURL(
+      `${BETA_API_ROOT}/networking/reserved/ips/${encodeURIComponent(ipAddress)}`,
+    ),
+    setMethod('DELETE'),
+  );
+
+/**
+ * getReservedIPsTypes
+ *
+ * Returns a paginated list of available Reserved IP types; used for pricing.
+ */
+export const getReservedIPsTypes = (params?: Params) =>
+  Request<Page<PriceType>>(
+    setURL(`${API_ROOT}/networking/reserved/ips/types`),
+    setMethod('GET'),
+    setParams(params),
+  );

packages/api-v4/src/networking/types.ts

@@ -1,13 +1,23 @@
+export interface AssignedEntity {
+  id: number;
+  label: string;
+  type: string;
+  url: string;
+}
+
 export interface IPAddress {
   address: string;
+  assigned_entity: AssignedEntity | null;
   gateway: null | string;
   interface_id: null | number;
-  linode_id: number;
+  linode_id: null | number;
   prefix: number;
   public: boolean;
   rdns: null | string;
   region: string;
+  reserved: boolean;
   subnet_mask: string;
+  tags: string[];
   type: string;
   vpc_nat_1_1?: null | {
     address: string;
@@ -16,6 +26,14 @@ export interface IPAddress {
   };
 }
 
+export interface AllocateIPPayload {
+  linode_id?: number;
+  public: boolean;
+  region?: string;
+  reserved?: boolean;
+  type: string;
+}
+
 export interface IPRangeBaseData {
   prefix: number;
   range: string;
@@ -51,3 +69,8 @@ export interface CreateIPv6RangePayload {
   prefix_length: IPv6Prefix;
   route_target?: string;
 }
+
+export interface ReserveIPPayload {
+  region: string;
+  tags?: string[];
+}

packages/api-v4/src/nodebalancers/types.ts

@@ -253,6 +253,7 @@ export interface CreateNodeBalancerPayload {
   client_udp_sess_throttle?: number;
   configs: CreateNodeBalancerConfig[];
   firewall_id?: number;
+  ipv4?: string; // must be a reserved unassigned IP owned by the customer.
   label?: string;
   region?: string;
   tags?: string[];

packages/api-v4/src/tags/types.ts

@@ -3,6 +3,10 @@ export interface Tag {
 }
 
 export interface TagRequest {
+  domains?: number[];
   label: string;
   linodes?: number[];
+  nodebalancers?: number[];
+  reserved_ipv4_addresses?: string[];
+  volumes?: number[];
 }

packages/manager/.changeset/pr-13517-upcoming-features-1774354565322.md

@@ -0,0 +1,5 @@
+---
+"@linode/manager": Upcoming Features
+---
+
+Reserved IPs - Add new endpoints, types and Queries ([#13517](https://github.com/linode/manager/pull/13517))

packages/manager/src/factories/networking.ts

@@ -4,6 +4,7 @@ import type { IPAddress } from '@linode/api-v4/lib/networking';
 
 export const ipAddressFactory = Factory.Sync.makeFactory<IPAddress>({
   address: Factory.each((id) => `192.168.1.${id}`),
+  assigned_entity: null,
   gateway: Factory.each((id) => `192.168.1.${id + 1}`),
   interface_id: Factory.each((id) => id),
   linode_id: Factory.each((id) => id),
@@ -13,4 +14,6 @@ export const ipAddressFactory = Factory.Sync.makeFactory<IPAddress>({
   region: 'us-east',
   subnet_mask: Factory.each((id) => `192.168.1.${id + 3}`),
   type: 'ipv4',
+  reserved: false,
+  tags: [],
 });

packages/manager/src/features/Linodes/LinodesDetail/LinodeNetworking/utils.ts

@@ -145,6 +145,7 @@ const ipAddressForVPC = (
 ): IPAddress => {
   return {
     address: ipAddress,
+    assigned_entity: null,
     gateway: ip.gateway,
     interface_id: ip.interface_id,
     linode_id: ip.linode_id!,
@@ -154,6 +155,8 @@ const ipAddressForVPC = (
     region: ip.region,
     subnet_mask: ip.subnet_mask,
     type: ipType,
+    reserved: false,
+    tags: [],
   };
 };
 

packages/queries/.changeset/pr-13517-upcoming-features-1774273217324.md

@@ -0,0 +1,5 @@
+---
+"@linode/queries": Upcoming Features
+---
+
+Reserved IPs: Added queries for Reserved IPs ([#13517](https://github.com/linode/manager/pull/13517))

packages/queries/src/networking/networking.ts

@@ -1,6 +1,15 @@
-import { createIPv6Range, getIPv6RangeInfo } from '@linode/api-v4';
+import {
+  createIPv6Range,
+  getIPv6RangeInfo,
+  getReservedIP,
+  getReservedIPs,
+  reserveIP,
+  unReserveIP,
+  updateReservedIP,
+} from '@linode/api-v4';
 import { createQueryKeys } from '@lukemorales/query-key-factory';
 import {
+  keepPreviousData,
   useMutation,
   useQueries,
   useQuery,
@@ -19,6 +28,8 @@ import type {
   IPRange,
   IPRangeInformation,
   Params,
+  ReserveIPPayload,
+  ResourcePage,
 } from '@linode/api-v4';
 
 export const networkingQueries = createQueryKeys('networking', {
@@ -39,6 +50,14 @@ export const networkingQueries = createQueryKeys('networking', {
     },
     queryKey: null,
   },
+  reservedIPs: (params: Params = {}, filter: Filter = {}) => ({
+    queryFn: () => getReservedIPs(params, filter),
+    queryKey: [params, filter],
+  }),
+  reservedIP: (address: string) => ({
+    queryFn: () => getReservedIP(address),
+    queryKey: [address],
+  }),
 });
 
 export const useAllIPsQuery = (
@@ -119,3 +138,72 @@ export const useCreateIPv6RangeMutation = () => {
     },
   });
 };
+
+export const useReservedIPsQuery = (
+  params?: Params,
+  filter?: Filter,
+  enabled: boolean = true,
+) => {
+  return useQuery<ResourcePage<IPAddress>, APIError[]>({
+    ...networkingQueries.reservedIPs(params, filter),
+    enabled,
+    placeholderData: keepPreviousData,
+  });
+};
+
+export const useReservedIPQuery = (address: string, enabled: boolean = true) =>
+  useQuery<IPAddress, APIError[]>({
+    ...networkingQueries.reservedIP(address),
+    enabled,
+  });
+
+export const useReserveIPMutation = () => {
+  const queryClient = useQueryClient();
+  return useMutation<IPAddress, APIError[], ReserveIPPayload>({
+    mutationFn: reserveIP,
+    onSuccess(reservedIP) {
+      queryClient.invalidateQueries({
+        queryKey: networkingQueries.reservedIPs._def,
+      });
+      queryClient.setQueryData<IPAddress>(
+        networkingQueries.reservedIP(reservedIP.address).queryKey,
+        reservedIP,
+      );
+    },
+  });
+};
+
+export const useUpdateReservedIPMutation = (address: string) => {
+  const queryClient = useQueryClient();
+  return useMutation<
+    IPAddress,
+    APIError[],
+    { address: string; tags: null | string[] }
+  >({
+    mutationFn: (data) => updateReservedIP(address, data.tags),
+    onSuccess(reservedIP) {
+      queryClient.invalidateQueries({
+        queryKey: networkingQueries.reservedIPs._def,
+      });
+      queryClient.setQueryData<IPAddress>(
+        networkingQueries.reservedIP(reservedIP.address).queryKey,
+        reservedIP,
+      );
+    },
+  });
+};
+
+export const useUnReserveIPMutation = (address: string) => {
+  const queryClient = useQueryClient();
+  return useMutation<object, APIError[]>({
+    mutationFn: () => unReserveIP(address),
+    onSuccess() {
+      queryClient.invalidateQueries({
+        queryKey: networkingQueries.reservedIPs._def,
+      });
+      queryClient.removeQueries({
+        queryKey: networkingQueries.reservedIP(address).queryKey,
+      });
+    },
+  });
+};