From 881523417b70983ad4eb3119601b2e34a071ba62 Mon Sep 17 00:00:00 2001 From: Christopher Tauchen Date: Mon, 4 Nov 2024 20:14:10 +0000 Subject: [PATCH] Docs edits. --- .../about.mdx | 0 .../getting-started/bare-metal/index.mdx | 18 +-- .../content/_non-cluster-binary-install.mdx | 149 ------------------ .../getting-started/bare-metal/about.mdx | 143 +++++++++++++++++ .../getting-started/bare-metal}/index.mdx | 0 .../install-on-non-cluster-hosts/index.mdx | 11 -- .../version-3.20-2-sidebars.json | 4 +- sidebars-calico-enterprise.js | 4 +- 8 files changed, 156 insertions(+), 173 deletions(-) rename calico-enterprise/getting-started/{install-on-non-cluster-hosts => bare-metal}/about.mdx (100%) rename calico-enterprise_versioned_docs/version-3.20-2/getting-started/install-on-non-cluster-hosts/about.mdx => calico-enterprise/getting-started/bare-metal/index.mdx (92%) delete mode 100644 calico-enterprise_versioned_docs/version-3.20-2/_includes/content/_non-cluster-binary-install.mdx create mode 100644 calico-enterprise_versioned_docs/version-3.20-2/getting-started/bare-metal/about.mdx rename {calico-enterprise/getting-started/install-on-non-cluster-hosts => calico-enterprise_versioned_docs/version-3.20-2/getting-started/bare-metal}/index.mdx (100%) delete mode 100644 calico-enterprise_versioned_docs/version-3.20-2/getting-started/install-on-non-cluster-hosts/index.mdx diff --git a/calico-enterprise/getting-started/install-on-non-cluster-hosts/about.mdx b/calico-enterprise/getting-started/bare-metal/about.mdx similarity index 100% rename from calico-enterprise/getting-started/install-on-non-cluster-hosts/about.mdx rename to calico-enterprise/getting-started/bare-metal/about.mdx diff --git a/calico-enterprise_versioned_docs/version-3.20-2/getting-started/install-on-non-cluster-hosts/about.mdx b/calico-enterprise/getting-started/bare-metal/index.mdx similarity index 92% rename from calico-enterprise_versioned_docs/version-3.20-2/getting-started/install-on-non-cluster-hosts/about.mdx rename to calico-enterprise/getting-started/bare-metal/index.mdx index 55b814db46..ba6e09b271 100644 --- a/calico-enterprise_versioned_docs/version-3.20-2/getting-started/install-on-non-cluster-hosts/about.mdx +++ b/calico-enterprise/getting-started/bare-metal/index.mdx @@ -98,21 +98,21 @@ Step 1: Install Calico node and fluent-bit log forwarder packages. - If your non-cluster host or VM has RHEL 8 installed, then run the following command: -```bash -dnf install https://downloads.tigera.io/ee/archives/calico-node-3.20~pre2.0.el8.x86_64.rpm -dnf install https://downloads.tigera.io/ee/archives/calico-fluent-bit-3.1.8.el8.x86_64.rpm -``` + ```bash + dnf install https://downloads.tigera.io/ee/archives/calico-node-3.20~pre2.0.el8.x86_64.rpm + dnf install https://downloads.tigera.io/ee/archives/calico-fluent-bit-3.1.8.el8.x86_64.rpm + ``` - If your non-cluster host or VM has RHEL 9 installed, then run the following command: -```bash -dnf install https://downloads.tigera.io/ee/archives/calico-node-3.20~pre2.0.el9.x86_64.rpm -dnf install https://downloads.tigera.io/ee/archives/calico-fluent-bit-3.1.8.el9.x86_64.rpm -``` + ```bash + dnf install https://downloads.tigera.io/ee/archives/calico-node-3.20~pre2.0.el9.x86_64.rpm + dnf install https://downloads.tigera.io/ee/archives/calico-fluent-bit-3.1.8.el9.x86_64.rpm + ``` Only Red Hat Enterprise Linux 8 and 9 x86-64 operating systems are supported in this version of {{prodname}}. -Step 2: Copy the kubeconfig created in Cluster setup step 3 to host folder `/etc/calico/kubeconfig` and change ownership to `calico:calico`. +Step 2: Copy the kubeconfig created in cluster setup step 3 to host folder `/etc/calico/kubeconfig` and change ownership to `calico:calico`. Step 3: Start Calico node and log forwarder. diff --git a/calico-enterprise_versioned_docs/version-3.20-2/_includes/content/_non-cluster-binary-install.mdx b/calico-enterprise_versioned_docs/version-3.20-2/_includes/content/_non-cluster-binary-install.mdx deleted file mode 100644 index b9f2b10cdc..0000000000 --- a/calico-enterprise_versioned_docs/version-3.20-2/_includes/content/_non-cluster-binary-install.mdx +++ /dev/null @@ -1,149 +0,0 @@ -import NonClusterReadOnlyStep from '@site/calico-enterprise_versioned_docs/version-3.20-2/_includes/content/_non-cluster-read-only-step.mdx'; -import EnvironmentFile from '@site/calico-enterprise_versioned_docs/version-3.20-2/_includes/components/EnvironmentFile'; - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - - - -### Step 2: Download and extract the binary - -This step requires Docker, but it can be run from any machine with Docker installed. It doesn't have to be the host you will run it on (i.e your laptop is fine). - -1. Use the following command to download the {{nodecontainer}} image. - - ```bash - docker pull {{registry}}{{componentImage.cnxNode}} - ``` - -1. Confirm that the image has loaded by typing `docker images`. - - ``` - REPOSITORY TAG IMAGE ID CREATED SIZE - {{registry}}{{ releases.0.components.cnx-node.image }} {{ releases.0.components.cnx-node.version }} e07d59b0eb8a 2 minutes ago 42MB - ``` - -1. Create a temporary {{nodecontainer}} container. - - ```bash - docker create --name container {{registry}}{{componentImage.cnxNode}} - ``` - -1. Copy the calico-node binary from the container to the local file system. - - ```bash - docker cp container:/bin/calico-node {{nodecontainer}} - ``` - -1. Delete the temporary container. - - ```bash - docker rm container - ``` - -1. Set the extracted binary file to be executable. - - ```bash - chmod +x {{nodecontainer}} - chown root:root {{nodecontainer}} - ``` - -### Step 3: Copy the `calico-node` binary - -Copy the binary from Step 2 to the target machine, using any means (`scp`, `ftp`, USB stick, etc.). - -### Step 4: Create environment file - - - -### Step 5: Start Felix - -There are a few ways to start Felix: create a startup script, or manually configure Felix. - - - - -Felix should be started at boot by your init system and the init system -**must** be configured to restart Felix if it stops. Felix relies on -that behavior for certain configuration changes. - -If your distribution uses systemd, then you could use the following unit file: - -```bash -[Unit] -Description=Calico Felix agent -After=syslog.target network.target - -[Service] -User=root -EnvironmentFile=/etc/calico/calico.env -ExecStartPre=/usr/bin/mkdir -p /var/run/calico -ExecStart=/usr/local/bin/{{nodecontainer}} -felix -KillMode=process -Restart=on-failure -LimitNOFILE=32000 - -[Install] -WantedBy=multi-user.target -``` - -Or, for upstart: - -```bash -description "Felix (Calico agent)" -author "Project Calico Maintainers " - -start on stopped rc RUNLEVEL=[2345] -stop on runlevel [!2345] - -limit nofile 32000 32000 - -respawn -respawn limit 5 10 - -chdir /var/run - -pre-start script - mkdir -p /var/run/calico - chown root:root /var/run/calico -end script - -exec /usr/local/bin/{{nodecontainer}} -felix -``` - -**Start Felix** - -After you've configured Felix, start it via your init system. - -```bash -service calico-felix start -``` - - - - -Configure Felix by creating a file at `/kubernetes/calico/felix.cfg`. -See [Felix configuration](../../reference/component-resources/node/felix/configuration.mdx) for help with environment variables. - -:::note - -Felix tries to detect whether IPv6 is available on your platform but -the detection can fail on older (or more unusual) systems. If Felix -exits soon after startup with `ipset` or `iptables` errors try -setting the `Ipv6Support` setting to `false`. - -::: - -Next, configure Felix to interact with a Kubernetes datastore. You -must set the `DatastoreType` setting to `kubernetes`. You must also set the environment variable `CALICO_KUBECONFIG` -to point to a valid kubeconfig for your kubernetes cluster and `CALICO_NETWORKING_BACKEND` to `none`. - -:::note - -For the Kubernetes datastore, Felix works in policy-only mode. Even though pod networking is -disabled on the baremetal host Felix is running on, policy can still be used to secure the host. - -::: - - - diff --git a/calico-enterprise_versioned_docs/version-3.20-2/getting-started/bare-metal/about.mdx b/calico-enterprise_versioned_docs/version-3.20-2/getting-started/bare-metal/about.mdx new file mode 100644 index 0000000000..f790d74ea9 --- /dev/null +++ b/calico-enterprise_versioned_docs/version-3.20-2/getting-started/bare-metal/about.mdx @@ -0,0 +1,143 @@ +--- +description: Install Calico on non-cluster hosts and VMs +--- + +# Install Calico on non-cluster hosts and VMs + +## Big picture + +Secure hosts and virtual machines (VMs) running outside of Kubernetes by installing {{prodname}}. + +## Value + +Calico Enterprise can also be used to protect hosts and VMs running outside of a Kubernetes cluster. In many cases, these are applications and workloads that cannot be easily containerized. {{prodname}} lets you protect and gain visibility into these **non-cluster hosts** and use the same robust Calico network policy that you use for pods. + +## Concepts + +### Non-cluster hosts and host endpoints + +A non-cluster host or VM is a computer that is running an application that is _not part of a Kubernetes cluster_. {{prodname}} enables you to protect these hosts and VMs using the same Calico network policy that you use for workloads running inside a Kubernetes cluster. It also generates flow logs that provide visibility into the communication that host or VM is having with other endpoints in your environment. + +In the following diagram, a Kubernetes cluster is running {{prodname}} with networking (for pod-to-pod communication) and network policy; the non-cluster host uses Calico network policy for host protection and to generate flow logs for observability. + +![non-cluster-host](/img/calico-enterprise/non-cluster-host.png) + +For non-cluster hosts and VMs, you can secure host interfaces using **host endpoints**. Host endpoints can have labels that work the same as labels on pods/workload endpoints in Kubernetes. The advantage is that you can write network policy rules to apply to both workload endpoints and host endpoints using label selectors; where each selector can refer to the either type (or be a mix of the two). For example, you can easily write a global policy that applies to every host, VM, or pod that is running Calico. + +To learn how to restrict traffic to/from hosts using Calico network policy see, [Protect hosts and VMs](../../network-policy/hosts/protect-hosts.mdx). + +## Before you begin + +**Required** + +- Kubernetes API datastore is up and running and is accessible from the host + + If {{prodname}} is installed on a cluster, you already have a datastore. + +- Non-cluster host or VM meets {{prodname}} [system requirements](../install-on-clusters/requirements.mdx) + + Ensure that your node OS includes the `ipset` and `conntrack` kernel dependencies. + +## How to + +### Set up your Kubernetes cluster to work with a non-cluster host or VM + +1. Apply the `NonClusterHost` custom resource. The `endpoint` field is required. It defines the remote endpoint for the non-cluster host log forwarder. + + ```bash + kubectl create -f - < + EOF + ``` + + Wait until the manager shows a status of Available, then proceed to the next step. + +1. Obtain the token for `tigera-noncluster-host` service account. + + ```bash + kubectl get secret -n calico-system tigera-noncluster-host -o jsonpath='{.data.token}' | base64 --decode + ``` + +1. Use a text editor to create a kubeconfig file for non-cluster host or VM. + + ```yaml + apiVersion: v1 + kind: Config + current-context: noncluster-hosts + preferences: {} + clusters: + - cluster: + Certificate-authority-data: + server: + name: noncluster-hosts + contexts: + - context: + cluster: noncluster-hosts + user: tigera-noncluster-host + name: noncluster-hosts + users: + - name: tigera-noncluster-host + user: + token: + ``` + + Take the cluster information from an already existing kubeconfig. + +1. Create a [`HostEndpoint` resource](../../reference/host-endpoints/overview.mdx) for each non-cluster host or VM. The `node` and `expectedIPs` fields are required to match the hostname and the expected interface IP addresses. + +1. Follow [Configure access to {{prodname}} Manager UI](../../operations/cnx/access-the-manager.mdx) page to configure {{prodname}} Manager access. + +### Set up your non-cluster host or VM + +1. Install Calico node and fluent-bit log forwarder packages. + + - If your non-cluster host or VM has RHEL 8 installed, then run the following command: + + ```bash + dnf install https://downloads.tigera.io/ee/archives/calico-node-3.20~pre2.0.el8.x86_64.rpm + dnf install https://downloads.tigera.io/ee/archives/calico-fluent-bit-3.1.8.el8.x86_64.rpm + ``` + + - If your non-cluster host or VM has RHEL 9 installed, then run the following command: + + ```bash + dnf install https://downloads.tigera.io/ee/archives/calico-node-3.20~pre2.0.el9.x86_64.rpm + dnf install https://downloads.tigera.io/ee/archives/calico-fluent-bit-3.1.8.el9.x86_64.rpm + ``` + + Only Red Hat Enterprise Linux 8 and 9 x86-64 operating systems are supported in this version of {{prodname}}. + +1. Copy the kubeconfig created in cluster setup step 3 to host folder `/etc/calico/kubeconfig` and change ownership to `calico:calico`. + +1. Start Calico node and log forwarder. + + ```bash + systemctl start calico-node.service + systemctl start calico-fluent-bit.service + ``` + + You can configure the Calico node by tuning the environment variables defined in the `/etc/calico/calico-node/calico-node.env` file. For more information, see the [Felix configuration reference](../../reference/resources/felixconfig.mdx). + +### Configure hosts to communicate with your Kubernetes cluster + +Using {{prodname}} network policy-only mode (i.e. with other CNIs), you must ensure that the non-cluster host or VM can directly communicate with your Kubernetes cluster. Here are some vendor tips: + +#### AWS + +- For hosts to communicate with your Kubernetes cluster, the node must be in the same VPC as nodes in your Kubernetes cluster, and must use the AWS VPC CNI plugin (used by default in EKS). +- The Kubernetes cluster security group needs to allow traffic from your host endpoint. Make sure that an inbound rule is set so that traffic from your host endpoint node is allowed. +- For a non-cluster host to communicate with an EKS cluster, the correct IAM roles must be configured. +- You also need to provide authentication to your Kubernetes cluster using [aws-iam-authenticator](https://docs.aws.amazon.com/eks/latest/userguide/install-aws-iam-authenticator.html) and the [aws cli](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) + +#### GKE + +For hosts to communicate with your Kubernetes cluster directly, you must make the host directly reachable/routable; this is not set up by default with the VPC native network routing. + +## Additional resources + +- [Protect hosts and VMs](../../network-policy/hosts/protect-hosts.mdx) diff --git a/calico-enterprise/getting-started/install-on-non-cluster-hosts/index.mdx b/calico-enterprise_versioned_docs/version-3.20-2/getting-started/bare-metal/index.mdx similarity index 100% rename from calico-enterprise/getting-started/install-on-non-cluster-hosts/index.mdx rename to calico-enterprise_versioned_docs/version-3.20-2/getting-started/bare-metal/index.mdx diff --git a/calico-enterprise_versioned_docs/version-3.20-2/getting-started/install-on-non-cluster-hosts/index.mdx b/calico-enterprise_versioned_docs/version-3.20-2/getting-started/install-on-non-cluster-hosts/index.mdx deleted file mode 100644 index d53454ee53..0000000000 --- a/calico-enterprise_versioned_docs/version-3.20-2/getting-started/install-on-non-cluster-hosts/index.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -description: Install Calico Enterprise on hosts to secure host communications. -hide_table_of_contents: true ---- - -# Non-cluster hosts - -import DocCardList from '@theme/DocCardList'; -import { useCurrentSidebarCategory } from '@docusaurus/theme-common'; - - diff --git a/calico-enterprise_versioned_sidebars/version-3.20-2-sidebars.json b/calico-enterprise_versioned_sidebars/version-3.20-2-sidebars.json index 3c016595b4..d0d08688ab 100644 --- a/calico-enterprise_versioned_sidebars/version-3.20-2-sidebars.json +++ b/calico-enterprise_versioned_sidebars/version-3.20-2-sidebars.json @@ -118,10 +118,10 @@ "label": "Install on non-cluster hosts", "link": { "type": "doc", - "id": "getting-started/install-on-non-cluster-hosts/index" + "id": "getting-started/bare-metal/index" }, "items": [ - "getting-started/install-on-non-cluster-hosts/about" + "getting-started/bare-metal/about" ] }, { diff --git a/sidebars-calico-enterprise.js b/sidebars-calico-enterprise.js index ede8ab3262..50e2992f93 100644 --- a/sidebars-calico-enterprise.js +++ b/sidebars-calico-enterprise.js @@ -95,8 +95,8 @@ module.exports = { { type: 'category', label: 'Install on non-cluster hosts', - link: { type: 'doc', id: 'getting-started/install-on-non-cluster-hosts/index' }, - items: ['getting-started/install-on-non-cluster-hosts/about'], + link: { type: 'doc', id: 'getting-started/bare-metal/index' }, + items: ['getting-started/bare-metal/about'], }, { type: 'category',