docs(samples): Adding Windows server samples (#274)

* docs(samples): Adding Windows instance related sampels

Co-authored-by: Anthonios Partheniou <partheniou@google.com>

samples/ingredients/firewall/windows_kms.py

@@ -0,0 +1,62 @@
+#  Copyright 2022 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+# This is an ingredient file. It is not meant to be run directly. Check the samples/snippets
+# folder for complete code samples that are ready to be used.
+# Disabling flake8 for the ingredients file, as it would fail F821 - undefined name check.
+# flake8: noqa
+
+from google.cloud import compute_v1
+
+
+# <INGREDIENT create_firewall_rule_for_windows_activation_host>
+def create_firewall_rule_for_windows_activation_host(
+    project_id: str, firewall_rule_name: str, network: str = "global/networks/default"
+) -> compute_v1.Firewall:
+    """
+    Creates an egress firewall rule with the highest priority for host
+    kms.windows.googlecloud.com (35.190.247.13) for Windows activation.
+
+    Args:
+        project_id: project ID or project number of the Cloud project you want to use.
+        firewall_rule_name: name of the rule that is created.
+        network: name of the network the rule will be applied to. Available name formats:
+            * https://www.googleapis.com/compute/v1/projects/{project_id}/global/networks/{network}
+            * projects/{project_id}/global/networks/{network}
+            * global/networks/{network}
+
+    Returns:
+        A Firewall object.
+    """
+    firewall_rule = compute_v1.Firewall()
+    firewall_rule.name = firewall_rule_name
+    firewall_rule.network = network
+
+    allowed = compute_v1.Allowed()
+    allowed.ports = ['1688']
+    allowed.I_p_protocol = 'tcp'
+
+    firewall_rule.allowed = [allowed]
+    firewall_rule.destination_ranges = ["35.190.247.13/32"]
+    firewall_rule.direction = compute_v1.Firewall.Direction.EGRESS.name
+    firewall_rule.priority = 0
+
+    firewall_client = compute_v1.FirewallsClient()
+    operation = firewall_client.insert(project=project_id, firewall_resource=firewall_rule)
+
+    wait_for_extended_operation(operation, "windows KSM firewall rule creation")
+
+    return firewall_client.get(project=project_id, firewall=firewall_rule_name)
+# </INGREDIENT>
+

samples/ingredients/instances/create_start_instance/create_windows_instance.py

@@ -0,0 +1,75 @@
+#  Copyright 2022 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+# This is an ingredient file. It is not meant to be run directly. Check the samples/snippets
+# folder for complete code samples that are ready to be used.
+# Disabling flake8 for the ingredients file, as it would fail F821 - undefined name check.
+# flake8: noqa
+from typing import Optional
+
+from google.cloud import compute_v1
+
+
+# <INGREDIENT create_windows_instance>
+def create_windows_instance(project_id: str, zone: str, instance_name: str,
+                            machine_type: str, source_image_family: str = "windows-2022",
+                            network_link: str = "global/networks/default",
+                            subnetwork_link: Optional[str] = None) -> compute_v1.Instance:
+    """
+    Creates a new Windows Server instance that has only an internal IP address.
+
+    Args:
+        project_id: project ID or project number of the Cloud project you want to use.
+        zone: name of the zone to create the instance in. For example: "us-west3-b"
+        instance_name: name of the new virtual machine (VM) instance.
+        machine_type: machine type you want to create in following format:
+            "zones/{zone}/machineTypes/{type_name}". For example:
+            "zones/europe-west3-c/machineTypes/f1-micro"
+            You can find the list of available machine types using:
+            https://cloud.google.com/sdk/gcloud/reference/compute/machine-types/list
+        source_image_family: name of the public image family for Windows Server or SQL Server images.
+            https://cloud.google.com/compute/docs/images#os-compute-support
+        network_link: name of the network you want the new instance to use.
+            For example: "global/networks/default" represents the network
+            named "default", which is created automatically for each project.
+        subnetwork_link: name of the subnetwork you want the new instance to use.
+            This value uses the following format:
+           "regions/{region}/subnetworks/{subnetwork_name}"
+
+    Returns:
+        Instance object.
+    """
+    if subnetwork_link is None:
+        subnetwork_link = f'regions/{zone}/subnetworks/default'
+
+    base_image = get_image_from_family(
+        project="windows-cloud", family=source_image_family
+    )
+    disk_type = f"zones/{zone}/diskTypes/pd-standard"
+    disks = [disk_from_image(disk_type, 100, True, base_image.self_link, True)]
+
+    # You must verify or configure routes and firewall rules in your VPC network
+    # to allow access to kms.windows.googlecloud.com.
+    # More information about access to kms.windows.googlecloud.com: https://cloud.google.com/compute/docs/instances/windows/creating-managing-windows-instances#kms-server
+
+    # Additionally, you must enable Private Google Access for subnets in your VPC network
+    # that contain Windows instances with only internal IP addresses.
+    # More information about Private Google Access: https://cloud.google.com/vpc/docs/configure-private-google-access#enabling
+
+    instance = create_instance(project_id, zone, instance_name, disks,
+                               machine_type=machine_type, network_link=network_link,
+                               subnetwork_link=subnetwork_link, external_access=True,
+                               )
+    return instance
+# </INGREDIENT>

samples/ingredients/instances/get_serial_port.py

@@ -0,0 +1,38 @@
+#  Copyright 2022 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+# This is an ingredient file. It is not meant to be run directly. Check the samples/snippets
+# folder for complete code samples that are ready to be used.
+# Disabling flake8 for the ingredients file, as it would fail F821 - undefined name check.
+# flake8: noqa
+from google.cloud import compute_v1
+
+
+# <INGREDIENT get_instance_serial_port_output>
+def get_instance_serial_port_output(project_id: str, zone: str, instance_name: str) -> compute_v1.SerialPortOutput:
+    """
+    Returns the last 1 MB of serial port output from the specified instance.
+
+    Args:
+        project_id: project ID or project number of the Cloud project you want to use.
+        zone: name of the zone you want to use. For example: “us-west3-b”
+        instance_name: name of the VM instance you want to query.
+    Returns:
+        Content of the serial port output of an instance inside a compute_v1.SerialPortOutput object.
+        More about this type: https://cloud.google.com/python/docs/reference/compute/latest/google.cloud.compute_v1.types.SerialPortOutput
+
+    """
+    instance_client = compute_v1.InstancesClient()
+    return instance_client.get_serial_port_output(project=project_id, zone=zone, instance=instance_name)
+# </INGREDIENT>

samples/ingredients/routes/create.py

@@ -0,0 +1,84 @@
+#  Copyright 2022 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+# This is an ingredient file. It is not meant to be run directly. Check the samples/snippets
+# folder for complete code samples that are ready to be used.
+# Disabling flake8 for the ingredients file, as it would fail F821 - undefined name check.
+# flake8: noqa
+from typing import Optional
+
+from google.cloud import compute_v1
+
+
+# <INGREDIENT create_route>
+def create_route(project_id: str, network: str, route_name: str, destination_range: str, *,
+                 next_hop_gateway: Optional[str] = None,
+                 next_hop_ip: Optional[str] = None, next_hop_instance: Optional[str] = None,
+                 next_hop_vpn_tunnel: Optional[str] = None, next_hop_ilb: Optional[str] = None) -> compute_v1.Route:
+    """
+    Create a new route in selected network by providing a destination and next hop name.
+
+    Note: The set of {next_hop_gateway, next_hop_ip, next_hop_instance, next_hop_vpn_tunnel,
+        next_hop_ilb} is exclusive, you and only specify one of those parameters.
+
+    Args:
+        project_id: project ID or project number of the Cloud project you want to use.
+        network: name of the network the route will be created in. Available name formats:
+            * https://www.googleapis.com/compute/v1/projects/{project_id}/global/networks/{network}
+            * projects/{project_id}/global/networks/{network}
+            * global/networks/{network}
+        route_name: name of the new route.
+        destination_range: range of destination IPs this route should be applied to. E.g. 10.0.0.0/16.
+        next_hop_gateway: name of the gateway the traffic should be directed to.
+        next_hop_ip: IP address the traffic should be directed to.
+        next_hop_instance: name of the instance the traffic should be directed to. Name format:
+            "projects/{project}/zones/{zone}/instances/{instance_name}"
+        next_hop_vpn_tunnel: name of the VPN tunnel the traffic should be directed to. Name format:
+            "projects/{project}/regions/{region}/vpnTunnels/{vpn_tunnel_name}"
+        next_hop_ilb: name of a forwarding rule of the Internal Load Balancer the traffic
+            should be directed to. Name format:
+            "projects/{project}/regions/{region}/forwardingRules/{forwarding_rule_region}"
+
+    Returns:
+        A new compute_v1.Route object.
+    """
+    excl_args = {next_hop_instance, next_hop_ilb, next_hop_vpn_tunnel, next_hop_gateway, next_hop_ip}
+    args_set = sum(1 if arg is not None else 0 for arg in excl_args)
+
+    if args_set != 1:
+        raise RuntimeError("You must specify exactly one next_hop_* parameter.")
+
+    route = compute_v1.Route()
+    route.name = route_name
+    route.network = network
+    route.dest_range = destination_range
+
+    if next_hop_gateway:
+        route.next_hop_gateway = next_hop_gateway
+    elif next_hop_ip:
+        route.next_hop_ip = next_hop_ip
+    elif next_hop_instance:
+        route.next_hop_instance = next_hop_instance
+    elif next_hop_vpn_tunnel:
+        route.next_hop_vpn_tunnel = next_hop_vpn_tunnel
+    elif next_hop_ilb:
+        route.next_hop_ilb = next_hop_ilb
+
+    route_client = compute_v1.RoutesClient()
+    operation = route_client.insert(project=project_id, route_resource=route)
+
+    wait_for_extended_operation(operation, "route creation")
+
+    return route_client.get(project=project_id, route=route_name)
+# </INGREDIENT>

samples/ingredients/routes/delete.py

@@ -0,0 +1,40 @@
+#  Copyright 2022 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+# This is an ingredient file. It is not meant to be run directly. Check the samples/snippets
+# folder for complete code samples that are ready to be used.
+# Disabling flake8 for the ingredients file, as it would fail F821 - undefined name check.
+# flake8: noqa
+from typing import NoReturn
+
+from google.cloud import compute_v1
+
+
+# <INGREDIENT delete_route>
+def delete_route(project_id: str, route_name: str) -> NoReturn:
+    """
+    Delete a route in project.
+
+    Args:
+        project_id: project ID or project number of the Cloud project you want to use.
+        route_name: name of the route to delete.
+    """
+
+    route_client = compute_v1.RoutesClient()
+    operation = route_client.delete(project=project_id, route=route_name)
+
+    wait_for_extended_operation(operation, "route deletion")
+
+    return
+# </INGREDIENT>

samples/ingredients/routes/list.py

@@ -0,0 +1,38 @@
+#  Copyright 2022 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+# This is an ingredient file. It is not meant to be run directly. Check the samples/snippets
+# folder for complete code samples that are ready to be used.
+# Disabling flake8 for the ingredients file, as it would fail F821 - undefined name check.
+# flake8: noqa
+from typing import Iterable
+
+from google.cloud import compute_v1
+
+
+# <INGREDIENT list_routes>
+def list_routes(project_id: str, ) -> Iterable[compute_v1.Route]:
+    """
+    Lists routes in project.
+
+    Args:
+        project_id: project ID or project number of the Cloud project you want to use.
+
+    Returns:
+        An iterable collection of routes found in given project.
+    """
+
+    route_client = compute_v1.RoutesClient()
+    return route_client.list(project=project_id)
+# </INGREDIENT>

samples/recipes/firewall/windows_kms.py

@@ -0,0 +1,23 @@
+#  Copyright 2022 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+# flake8: noqa
+
+# <REGION compute_create_egress_rule_windows_activation>
+# <IMPORTS/>
+
+# <INGREDIENT wait_for_extended_operation />
+
+# <INGREDIENT create_firewall_rule_for_windows_activation_host />
+
+# </REGION compute_create_egress_rule_windows_activation>

samples/recipes/instances/create_start_instance/create_windows_instance.py

@@ -0,0 +1,31 @@
+#  Copyright 2022 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+# flake8: noqa
+
+# <REGION compute_create_windows_instance_internal_ip>
+# <IMPORTS/>
+
+# <INGREDIENT get_image_from_family />
+
+
+# <INGREDIENT disk_from_image />
+
+# <INGREDIENT wait_for_extended_operation />
+
+
+# <INGREDIENT create_instance />
+
+
+# <INGREDIENT create_windows_instance />
+# </REGION compute_create_windows_instance_internal_ip>