├── .gitignore ├── CONTRIBUTING.md ├── LICENSE ├── Makefile ├── OWNERS ├── README.md ├── RELEASE.md ├── SECURITY.md ├── SECURITY_CONTACTS ├── apis ├── doc.go ├── service_export.go └── service_import.go ├── code-of-conduct.md ├── docs └── index.md ├── mkdocs.yml ├── netlify.toml ├── requirements.txt └── site-src ├── api-types ├── cluster-set.md ├── service-export.md └── service-import.md ├── blog ├── 2022 │ └── 2022-11-16_archiving-kubefed-on-Jan-3-2023.md └── index.md ├── concepts ├── about-api.md ├── cluster-profile-api.md ├── multicluster-services-api.md ├── namespace-sameness.md └── work-api.md ├── contributing ├── faq.md └── index.md ├── guides ├── coredns.md ├── gateway-api.md ├── gke-mcs.md ├── guidelines.md ├── index.md ├── istio.md └── submariner-mcs.md ├── images ├── about-api.png ├── cluster-profile-api.png ├── k8s-favicon.png ├── mcs-overview.png ├── prepopulated-snippet.png ├── snippet-selection.png └── work-api.png ├── index.md └── references ├── README.md ├── spec.md └── yaml.json /.gitignore: -------------------------------------------------------------------------------- 1 | venv/ 2 | /site 3 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing Guidelines 2 | 3 | Welcome to Kubernetes. We are excited about the prospect of you joining our [community](https://git.k8s.io/community)! The Kubernetes community abides by the CNCF [code of conduct](code-of-conduct.md). Here is an excerpt: 4 | 5 | _As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities._ 6 | 7 | ## Getting Started 8 | 9 | We have full documentation on how to get started contributing here: 10 | 11 | 14 | 15 | - [Contributor License Agreement](https://git.k8s.io/community/CLA.md) Kubernetes projects require that you sign a Contributor License Agreement (CLA) before we can accept your pull requests 16 | - [Kubernetes Contributor Guide](https://git.k8s.io/community/contributors/guide) - Main contributor documentation, or you can just jump directly to the [contributing section](https://git.k8s.io/community/contributors/guide#contributing) 17 | - [Contributor Cheat Sheet](https://git.k8s.io/community/contributors/guide/contributor-cheatsheet) - Common resources for existing developers 18 | 19 | ## Mentorship 20 | 21 | - [Mentoring Initiatives](https://git.k8s.io/community/mentoring) - We have a diverse set of mentorship programs available that are always looking for volunteers! 22 | 23 | 32 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "{}" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright {yyyy} {name of copyright owner} 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Copyright 2019 The Kubernetes Authors. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | SHELL := /bin/bash 15 | 16 | all: docs 17 | 18 | # Install dependencies 19 | .PHONY: install 20 | install: 21 | # Create python virtual environment 22 | python3 -m venv venv/ 23 | 24 | # Activate virtual environment and install dependencies 25 | source ./venv/bin/activate && pip install -r requirements.txt 26 | 27 | 28 | # Build the documentation 29 | .PHONY: docs 30 | docs: install 31 | # Ensure site dir exists 32 | mkdir -p site 33 | 34 | # Generate docs with mkdocs 35 | source ./venv/bin/activate && mkdocs build 36 | 37 | 38 | # Cleanup local directory 39 | .PHONY: cleanup 40 | cleanup: 41 | # Remove python virtual environment 42 | rm -rf venv 43 | 44 | # Remove site build 45 | rm -rf site 46 | -------------------------------------------------------------------------------- /OWNERS: -------------------------------------------------------------------------------- 1 | # See the OWNERS docs at https://go.k8s.io/owners 2 | 3 | approvers: 4 | - jeremyot 5 | - lauralorenz 6 | - skitt 7 | 8 | emeritus_approvers: 9 | - pmorie 10 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # SIG-Multicluster website 2 | 3 | This repo holds and hosts the site for [SIG-Multicluster](https://multicluster.sigs.k8s.io/), 4 | a special interest group of the Kubernetes project. 5 | 6 | ## Community, discussion, contribution, and support 7 | 8 | Learn how to engage with the Multicluster Special Interest Group community on the 9 | [community page](https://github.com/kubernetes/community/tree/master/sig-multicluster#multicluster-special-interest-group/). 10 | 11 | You can reach the maintainers of this project at: 12 | 13 | - Slack: [#sig-multicluster](https://kubernetes.slack.com/messages/sig-multicluster/) 14 | - [Mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-multicluster/) 15 | 16 | ### Code of conduct 17 | 18 | Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](code-of-conduct.md). 19 | 20 | [owners]: https://git.k8s.io/community/contributors/guide/owners.md 21 | [Creative Commons 4.0]: https://git.k8s.io/website/LICENSE 22 | 23 | # Contributors 24 | 25 | ## Install and run 26 | 27 | Install Python and the requirements for this site using the included `Makefile`. 28 | 29 | ``` 30 | make install 31 | ``` 32 | 33 | Use the mkdocs CLI to serve a development version of the site. 34 | 35 | ```mkdocs serve``` 36 | 37 | Navigate to `localhost:8000` to see the site. 38 | 39 | ## Build and deploy 40 | 41 | Use the mkdocs CLI to deploy to the `gh-pages` branch of the repo. 42 | 43 | ```mkdocs gh-deploy``` 44 | -------------------------------------------------------------------------------- /RELEASE.md: -------------------------------------------------------------------------------- 1 | # Release Process 2 | 3 | The Kubernetes Template Project is released on an as-needed basis. The process is as follows: 4 | 5 | 1. An issue is proposing a new release with a changelog since the last release 6 | 1. All [OWNERS](OWNERS) must LGTM this release 7 | 1. An OWNER runs `git tag -s $VERSION` and inserts the changelog and pushes the tag with `git push $VERSION` 8 | 1. The release issue is closed 9 | 1. An announcement email is sent to `dev@kubernetes.io` with the subject `[ANNOUNCE] kubernetes-template-project $VERSION is released` 10 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | # Security Policy 2 | 3 | ## Security Announcements 4 | 5 | Join the [kubernetes-security-announce] group for security and vulnerability announcements. 6 | 7 | ## Reporting a Vulnerability 8 | 9 | Instructions for reporting a vulnerability can be found on the 10 | [Kubernetes Security and Disclosure Information] page. 11 | 12 | ## Supported Versions 13 | 14 | Information about supported Kubernetes versions can be found on the 15 | [Kubernetes version and version skew support policy] page on the Kubernetes website. 16 | 17 | [kubernetes-security-announce]: https://groups.google.com/forum/#!forum/kubernetes-security-announce 18 | [Kubernetes version and version skew support policy]: https://kubernetes.io/docs/setup/release/version-skew-policy/#supported-versions 19 | [Kubernetes Security and Disclosure Information]: https://kubernetes.io/docs/reference/issues-security/security/#report-a-vulnerability 20 | -------------------------------------------------------------------------------- /SECURITY_CONTACTS: -------------------------------------------------------------------------------- 1 | # Defined below are the security contacts for this repo. 2 | # 3 | # They are the contact point for the Security Response Committee to reach out 4 | # to for triaging and handling of incoming issues. 5 | # 6 | # The below names agree to abide by the 7 | # [Embargo Policy](https://git.k8s.io/security/private-distributors-list.md#embargo-policy) 8 | # and will be removed and replaced if they violate that agreement. 9 | # 10 | # DO NOT REPORT SECURITY VULNERABILITIES DIRECTLY TO THESE NAMES, FOLLOW THE 11 | # INSTRUCTIONS AT https://kubernetes.io/security/ 12 | 13 | jeremyot 14 | lauralorenz 15 | pmorie 16 | -------------------------------------------------------------------------------- /apis/doc.go: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2020 The Kubernetes Authors. 3 | 4 | Licensed under the Apache License, Version 2.0 (the "License"); 5 | you may not use this file except in compliance with the License. 6 | You may obtain a copy of the License at 7 | 8 | http://www.apache.org/licenses/LICENSE-2.0 9 | 10 | Unless required by applicable law or agreed to in writing, software 11 | distributed under the License is distributed on an "AS IS" BASIS, 12 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | See the License for the specific language governing permissions and 14 | limitations under the License. 15 | */ 16 | 17 | package apis 18 | -------------------------------------------------------------------------------- /apis/service_export.go: -------------------------------------------------------------------------------- 1 | package apis 2 | 3 | // ServiceExport declares that the associated service should be exported to 4 | // other clusters. 5 | type ServiceExport struct { 6 | metav1.TypeMeta `json:",inline"` 7 | // +optional 8 | metav1.ObjectMeta `json:"metadata,omitempty"` 9 | // +optional 10 | Status ServiceExportStatus `json:"status,omitempty"` 11 | } 12 | 13 | // ServiceExportStatus contains the current status of an export. 14 | type ServiceExportStatus struct { 15 | // +optional 16 | // +patchStrategy=merge 17 | // +patchMergeKey=type 18 | // +listType=map 19 | // +listMapKey=type 20 | Conditions []ServiceExportCondition `json:"conditions,omitempty"` 21 | } 22 | 23 | // ServiceExportConditionType identifies a specific condition. 24 | type ServiceExportConditionType string 25 | 26 | const { 27 | // ServiceExportValid means that the service referenced by this 28 | // service export has been recognized as valid by an mcs-controller. 29 | // This will be false if the service is found to be unexportable 30 | // (ExternalName, not found). 31 | ServiceExportValid ServiceExportConditionType = "Valid" 32 | // ServiceExportConflict means that there is a conflict between two 33 | // exports for the same Service. When "True", the condition message 34 | // should contain enough information to diagnose the conflict: 35 | // field(s) under contention, which cluster won, and why. 36 | // Users should not expect detailed per-cluster information in the 37 | // conflict message. 38 | ServiceExportConflict ServiceExportConditionType = "Conflict" 39 | } 40 | 41 | // ServiceExportCondition contains details for the current condition of this 42 | // service export. 43 | // 44 | // Once KEP-1623 (sig-api-machinery/1623-standardize-conditions) is 45 | // implemented, this will be replaced by metav1.Condition. 46 | type ServiceExportCondition struct { 47 | Type ServiceExportConditionType `json:"type"` 48 | // Status is one of {"True", "False", "Unknown"} 49 | Status corev1.ConditionStatus `json:"status"` 50 | // +optional 51 | LastTransitionTime *metav1.Time `json:"lastTransitionTime,omitempty"` 52 | // +optional 53 | Reason *string `json:"reason,omitempty"` 54 | // +optional 55 | Message *string `json:"message,omitempty"` 56 | } -------------------------------------------------------------------------------- /apis/service_import.go: -------------------------------------------------------------------------------- 1 | package apis 2 | 3 | // ServiceImport describes a service imported from clusters in a clusterset. 4 | type ServiceImport struct { 5 | metav1.TypeMeta `json:",inline"` 6 | // +optional 7 | metav1.ObjectMeta `json:"metadata,omitempty"` 8 | // +optional 9 | Spec ServiceImportSpec `json:"spec,omitempty"` 10 | // +optional 11 | Status ServiceImportStatus `json:"status,omitempty"` 12 | } 13 | 14 | // ServiceImportType designates the type of a ServiceImport 15 | type ServiceImportType string 16 | 17 | const ( 18 | // ClusterSetIP are only accessible via the ClusterSet IP. 19 | ClusterSetIP ServiceImportType = "ClusterSetIP" 20 | // Headless services allow backend pods to be addressed directly. 21 | Headless ServiceImportType = "Headless" 22 | ) 23 | 24 | // ServiceImportSpec describes an imported service and the information necessary to consume it. 25 | type ServiceImportSpec struct { 26 | // +listType=atomic 27 | Ports []ServicePort `json:"ports"` 28 | // +kubebuilder:validation:MaxItems:=1 29 | // +optional 30 | IPs []string `json:"ips,omitempty"` 31 | // +optional 32 | Type ServiceImportType `json:"type"` 33 | // +optional 34 | SessionAffinity corev1.ServiceAffinity `json:"sessionAffinity"` 35 | // +optional 36 | SessionAffinityConfig *corev1.SessionAffinityConfig `json:"sessionAffinityConfig"` 37 | } 38 | 39 | // ServicePort represents the port on which the service is exposed 40 | type ServicePort struct { 41 | // The name of this port within the service. This must be a DNS_LABEL. 42 | // All ports within a ServiceSpec must have unique names. When considering 43 | // the endpoints for a Service, this must match the 'name' field in the 44 | // EndpointPort. 45 | // Optional if only one ServicePort is defined on this service. 46 | // +optional 47 | Name string `json:"name,omitempty"` 48 | 49 | // The IP protocol for this port. Supports "TCP", "UDP", and "SCTP". 50 | // Default is TCP. 51 | // +optional 52 | Protocol Protocol `json:"protocol,omitempty"` 53 | 54 | // The application protocol for this port. 55 | // This field follows standard Kubernetes label syntax. 56 | // Un-prefixed names are reserved for IANA standard service names (as per 57 | // RFC-6335 and http://www.iana.org/assignments/service-names). 58 | // Non-standard protocols should use prefixed names such as 59 | // mycompany.com/my-custom-protocol. 60 | // Field can be enabled with ServiceAppProtocol feature gate. 61 | // +optional 62 | AppProtocol *string `json:"appProtocol,omitempty"` 63 | 64 | // The port that will be exposed by this service. 65 | Port int32 `json:"port"` 66 | } 67 | 68 | // ServiceImportStatus describes derived state of an imported service. 69 | type ServiceImportStatus struct { 70 | // +optional 71 | // +patchStrategy=merge 72 | // +patchMergeKey=cluster 73 | // +listType=map 74 | // +listMapKey=cluster 75 | Clusters []ClusterStatus `json:"clusters"` 76 | } 77 | 78 | // ClusterStatus contains service configuration mapped to a specific source cluster 79 | type ClusterStatus struct { 80 | Cluster string `json:"cluster"` 81 | } -------------------------------------------------------------------------------- /code-of-conduct.md: -------------------------------------------------------------------------------- 1 | # Kubernetes Community Code of Conduct 2 | 3 | Please refer to our [Kubernetes Community Code of Conduct](https://git.k8s.io/community/code-of-conduct.md) 4 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | # Welcome to MkDocs 2 | 3 | For full documentation visit [mkdocs.org](https://www.mkdocs.org). 4 | 5 | ## Commands 6 | 7 | * `mkdocs new [dir-name]` - Create a new project. 8 | * `mkdocs serve` - Start the live-reloading docs server. 9 | * `mkdocs build` - Build the documentation site. 10 | * `mkdocs -h` - Print help message and exit. 11 | 12 | ## Project layout 13 | 14 | mkdocs.yml # The configuration file. 15 | docs/ 16 | index.md # The documentation homepage. 17 | ... # Other markdown pages, images and other files. 18 | -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: SIG Multicluster 2 | repo_url: https://github.com/kubernetes-sigs/sig-multicluster-site 3 | repo_name: kubernetes-sigs/sig-multicluster-site 4 | site_dir: site 5 | docs_dir: site-src 6 | theme: 7 | name: material 8 | icon: 9 | repo: fontawesome/brands/git-alt 10 | logo: images/k8s-favicon.png 11 | favicon: images/k8s-favicon.png 12 | features: 13 | - search.highlight 14 | - navigation.tabs 15 | - navigation.top 16 | edit_uri: edit/main/site-src/ 17 | plugins: 18 | - search 19 | - awesome-pages 20 | - redirects: 21 | redirect_maps: 22 | 'guides/getting-started.md': 'guides/index.md' 23 | 'contributing/community.md': 'contributing/index.md' 24 | markdown_extensions: 25 | - admonition 26 | - meta 27 | - pymdownx.emoji: 28 | emoji_index: !!python/name:material.extensions.emoji.twemoji 29 | emoji_generator: !!python/name:material.extensions.emoji.to_svg 30 | - pymdownx.highlight 31 | - pymdownx.inlinehilite 32 | - pymdownx.superfences 33 | - pymdownx.snippets 34 | - toc: 35 | permalink: true 36 | nav: 37 | - Overview: 38 | - Introduction: index.md 39 | - About API Overview: concepts/about-api.md 40 | - Multicluster Services API Overview: concepts/multicluster-services-api.md 41 | - Work API Overview: concepts/work-api.md 42 | - ClusterProfile API Overview: concepts/cluster-profile-api.md 43 | - Guides: 44 | - Index: guides/index.md 45 | - Implementation Guidelines: guides/guidelines.md 46 | - Reference: 47 | - Namespace Sameness: concepts/namespace-sameness.md 48 | - ClusterSet: api-types/cluster-set.md 49 | - ServiceExport: api-types/service-export.md 50 | - ServiceImport: api-types/service-import.md 51 | - API specification: references/spec.md 52 | - Contributing: 53 | - How to Get Involved: contributing/index.md 54 | - FAQ: contributing/faq.md 55 | - Announcements: 56 | - Index: blog/index.md 57 | - 2022: 58 | - Archiving Kubefed on Jan 3rd, 2023: blog/2022/2022-11-16_archiving-kubefed-on-Jan-3-2023.md 59 | -------------------------------------------------------------------------------- /netlify.toml: -------------------------------------------------------------------------------- 1 | # Netlify build instructions 2 | [build] 3 | command = "make docs" 4 | publish = "site" 5 | environment = { PYTHON_VERSION = "3.8" } 6 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | mkdocs-material 2 | mkdocs-awesome-pages-plugin 3 | mkdocs-macros-plugin 4 | mkdocs-redirects 5 | -------------------------------------------------------------------------------- /site-src/api-types/cluster-set.md: -------------------------------------------------------------------------------- 1 | # ClusterSet 2 | 3 | ClusterSet represents a specific pattern implemented by various organizations. A ClusterSet is typically: 4 | 5 | - A group of clusters governed by a single authority. 6 | - There is usually a high degree of trust within the set of clusters. 7 | - [Namespace Sameness](../concepts/namespace-sameness.md) applies to clusters in the set: 8 | - Permissions and characteristics are consistent across clusters for a given namespace. 9 | - Namespaces don't have to exist in every cluster, but behave the same across those in which they do. 10 | 11 | !!!note 12 | The early definition of the ClusterSet was described in [KEP-2149](https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/2149-clusterid). It is now part of the [About API](https://sigs.k8s.io/about-api). 13 | 14 | A cluster's ClusterSet membership is stored in the about.k8s.io/ClusterProperty `clusterset.k8s.io`. 15 | 16 | ## Cluster Metadata 17 | The ClusterSet is a Cluster-scoped ClusterProperty CRD (Customer Resource Definition), that stores a name and a value. 18 | 19 | This property can be used to: 20 | 21 | - uniquely identify clusters using a clusterID 22 | 23 | ```yaml 24 | apiVersion: about.k8s.io/v1 25 | kind: ClusterProperty 26 | metadata: 27 | name: cluster.clusterset.k8s.io 28 | spec: 29 | value: cluster-1 30 | ``` 31 | 32 | - uniquely identify the membership of a cluster in a ClusterSet for the lifetime of the membership. 33 | 34 | ```yaml 35 | apiVersion: about.k8s.io/v1 36 | kind: ClusterProperty 37 | metadata: 38 | name: clusterset.k8s.io 39 | spec: 40 | value: mycoolclusterset 41 | ``` 42 | 43 | - Provide a reference point for multi-cluster tooling to build on within a cluster set, for example for DNS labels, for logging and tracing, etc. 44 | 45 | - Provide extra metadata space to store other cluster properties that might otherwise be implemented as ad-hoc annotations on semantically adjacent objects. 46 | 47 | ```yaml 48 | apiVersion: about.k8s.io/v1 49 | kind: ClusterProperty 50 | metadata: 51 | name: fingerprint.mycoolimplementation.com 52 | spec: 53 | value: '{"major": "1","minor": "18","gitVersion": "v1.18.2","gitCommit": "52c56ce7a8272c798dbc29846288d7cd9fbae032","gitTreeState": "clean","buildDate": "2020-04-30T20:19:45Z","goVersion": "go1.13.9","compiler": "gc","platform": "linux/amd64"}' 54 | ``` 55 | 56 | 57 | 58 | 59 | 60 | -------------------------------------------------------------------------------- /site-src/api-types/service-export.md: -------------------------------------------------------------------------------- 1 | # ServiceExport 2 | 3 | ## Resource Definition 4 | A ServiceExport is a Customer Resource Definition used to specify which Kubernetes Services should be exported within a cluster. 5 | 6 | A ServiceExport resource is created with the cluster and namespace that a given Service resides in, and is name-mapped to the service for export. In other words, the ServiceExport is referenced with the same name as the export. 7 | 8 | If multiple clusters export a Service with the same namespaced name, they will be recognized as a single combined service. 9 | 10 | ## DNS 11 | When a ServiceExport is created, this will cause a domain name for the multi-cluster service to become accessible from within the ClusterSet. The domain name will be `..svc.clusterset.local`. 12 | 13 | ## EndpointSlice 14 | When a ServiceExport is created, this will cause EndpointSlice objects for the underlying Service to be created in each cluster within the ClusterSet. One or more EndpointSlice resources will exist for each cluster that exported the Service, with each EndpointSlice containing only endpoints from its source cluster. These EndpointSlice objects are marked as managed by the ClusterSet service controller, so that the endpoint slice controller doesn’t delete them. 15 | -------------------------------------------------------------------------------- /site-src/api-types/service-import.md: -------------------------------------------------------------------------------- 1 | # ServiceImport -------------------------------------------------------------------------------- /site-src/blog/2022/2022-11-16_archiving-kubefed-on-Jan-3-2023.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Archiving Kubefed on Jan 3, 2023" 3 | date: 2022-11-16 4 | --- 5 | 6 | 7 | :octicons-calendar-24: November 16, 2022 · 8 | :octicons-clock-24: 5 min read 9 | 10 | 11 | As discussed over the past few SIG meetings, Kubecon, and this list, [KubeFed][kubefed-repo] is heading for archival. 12 | We plan to create the tombstone commit and complete the process in seven weeks on Jan 3, 2023 so that there's time to get any last changes into the main repo. 13 | This is meant to clarify the state of the ‘federation’ concept and associated projects in Kubernetes and to better set expectations around development and support in the area. Archiving will enable us to send a clear signal about the direction the SIG is headed in and how we will approach our work. 14 | 15 | **Archival is not deletion** and the code will remain on [GitHub][kubefed-repo] for reference or to fork and start your own projects. Nothing is going away and those who rely on kubefed can base new projects on the source, expanding and collaborating as you see fit. 16 | 17 | We want to thank everyone who has contributed to [Kubefed][kubefed-repo] over the past few years, it's been a huge effort from many people and has brought a ton of value to the community. We recognize and appreciate all of your hard work. 18 | 19 | While we don't have a SIG-endorsed replacement project and will not be linking to other projects from the tombstone, we will be linking to this thread. We welcome the community to chime in here with alternatives you're using or your own projects in the space. 20 | 21 | Thanks all! 22 | 23 | Jeremy Olmsted-Thompson 24 | Paul Morie 25 | 26 | SIG Multicluster Chairs 27 | 28 | [kubefed-repo]:https://github.com/kubernetes-sigs/kubefed -------------------------------------------------------------------------------- /site-src/blog/index.md: -------------------------------------------------------------------------------- 1 | # Announcements 2 | 3 | ## [Archiving Kubefed on January 3rd, 2023][Archiving Kubefed] 4 | 5 | 6 | :octicons-calendar-24: November 16, 2022 · 7 | :octicons-clock-24: 5 min read 8 | 9 | 10 | As discussed over the past few SIG meetings, Kubecon, and this list, [KubeFed][kubefed-repo] is heading for archival. 11 | 12 | We plan to create the tombstone commit and complete the process in seven weeks on Jan 3, 2023 so that there's time to get any last changes into the main repo. 13 | 14 | This is meant to clarify the state of the ‘federation’ concept and associated projects in Kubernetes and to better set expectations around development and support in the area. Archiving will enable us to send a clear signal about the direction the SIG is headed in and how we will approach our work. 15 | [:octicons-arrow-right-24: Continue reading][Archiving Kubefed] 16 | 17 | [Archiving Kubefed]: 2022/2022-11-16_archiving-kubefed-on-Jan-3-2023.md 18 | [kubefed-repo]:https://github.com/kubernetes-sigs/kubefed 19 | -------------------------------------------------------------------------------- /site-src/concepts/about-api.md: -------------------------------------------------------------------------------- 1 | # About API Overview 2 | 3 | This document provides an overview of the About API. 4 | 5 | ![Alt](../images/about-api.png "About API") 6 | 7 | The About API allows metadata to be attached to individual clusters. 8 | The fundamental resource defined in the API is the ClusterProperty CRD. 9 | 10 | You can read more details about the API in [KEP-2149](https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/2149-clusterid). 11 | 12 | ## ClusterProperty CRD 13 | 14 | The ClusterProperty CRD is proposed to give a Kubernetes-native way of identifying clusters, however, it can be used to store any metadata about a cluster. 15 | 16 | ### Example 17 | 18 | ```yaml 19 | apiVersion: about.k8s.io/v1 20 | kind: ClusterProperty 21 | metadata: 22 | name: cluster.clusterset.k8s.io 23 | spec: 24 | value: cluster-1 25 | ``` 26 | 27 | In the above example the ClusterProperty CRD is used to identify a cluster with the id of `cluster-1`. The key in this example `cluster.clusterset.k8s.io`, is one of the two proposed well-known properties. 28 | 29 | ### Well-known properties 30 | There are two well-known properties proposed: 31 | 32 | - `cluster.clusterset.k8s.io` A unique ID or name of the cluster. The value is implementation-specific, but it should be unique within the scope of the cluster set. 33 | - `clusterset.k8s.io` The cluster set that the cluster belongs to. A cluster which is part of a cluster set should have this property set. 34 | 35 | -------------------------------------------------------------------------------- /site-src/concepts/cluster-profile-api.md: -------------------------------------------------------------------------------- 1 | # ClusterProfile API Overview 2 | 3 | This document provides an overview of the [ClusterProfile API](https://github.com/kubernetes-sigs/cluster-inventory-api?tab=readme-ov-file#cluster-profile-api). 4 | 5 | ![Alt](../images/cluster-profile-api.png "ClusterProfile API") 6 | 7 | A Cluster Profile is a namespace-level resource and essentially represents an individual member of the Cluster Inventory 8 | that details properties and status of a cluster. This API proposes a standardized interface that defines how cluster information should be presented 9 | and interacted with across different platforms and implementations. 10 | 11 | You can read more details about the API in the [KEP-4322](https://github.com/kubernetes/enhancements/blob/master/keps/sig-multicluster/4322-cluster-inventory/README.md). 12 | 13 | ## Terminology 14 | 15 | - **Cluster Inventory**: A conceptual term referring to a collection of clusters. A cluster inventory may or may not represent 16 | a [ClusterSet](../api-types/cluster-set.md). A cluster inventory is considered a clusterSet if all its member clusters adhere to the 17 | [namespace sameness](https://github.com/kubernetes/community/blob/master/sig-multicluster/namespace-sameness-position-statement.md) principle. 18 | 19 | - **Cluster Manager**: An entity that creates the ClusterProfile API object per member cluster, 20 | and keeps their status up-to-date. Each cluster manager MUST be identified with a unique name. 21 | Each ClusterProfile resource SHOULD be managed by only one cluster manager. A cluster manager SHOULD 22 | have sufficient permission to access the member cluster to fetch the information so it can update the status 23 | of the ClusterProfile API resource. 24 | 25 | - **ClusterProfile API Consumer**: the person running the cluster managers 26 | or the person developing extensions for cluster managers for the purpose of 27 | workload distribution, operation management etc. 28 | 29 | ## API Example 30 | 31 | [CRD definition](https://github.com/kubernetes-sigs/cluster-inventory-api/blob/main/config/crd/bases/multicluster.x-k8s.io_clusterprofiles.yaml) 32 | 33 | ```yaml 34 | apiVersion: multicluster.x-k8s.io/v1alpha1 35 | kind: ClusterProfile 36 | metadata: 37 | name: some-cluster-name 38 | namespace: fleet-system 39 | labels: 40 | x-k8s.io/cluster-manager: some-cluster-manager 41 | spec: 42 | displayName: some-cluster 43 | clusterManager: 44 | name: some-cluster-manager 45 | status: 46 | version: 47 | kubernetes: 1.28.0 48 | properties: 49 | - name: clusterset.k8s.io 50 | value: some-clusterset 51 | - name: location 52 | value: apac 53 | conditions: 54 | - type: ControlPlaneHealthy 55 | status: True 56 | lastTransitionTime: "2023-05-08T07:56:55Z" 57 | message: "" 58 | - type: Joined 59 | status: True 60 | lastTransitionTime: "2023-05-08T07:58:55Z" 61 | message: "" 62 | ``` 63 | -------------------------------------------------------------------------------- /site-src/concepts/multicluster-services-api.md: -------------------------------------------------------------------------------- 1 | # Multicluster Services API Overview 2 | 3 | This document provides an overview of Multicluster Services API. 4 | 5 | This is an extension of the Services concept across multiple clusters. Services are the basic way that workloads communicate with each other in Kubernetes, and the Multicluster Services builds upon the [Namespace Sameness](./namespace-sameness.md) concept to extend Services across multiclusters. In short, Services can remain available across clusters simply by using the same names. The Control Plane can be centralized or decentralized, but consumers only rely on local data. 6 | 7 | This document solely focuses on the API and the common behaviour, leaving room for various [implementations](../guides/index.md). There is no reference implementation available. 8 | 9 | The intent of the Multicluster Services API is that ClusterIP and headless services just work as expected across clusters. 10 | 11 | You can read more details about the API in the [KEP-1645](https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/1645-multi-cluster-services-api). 12 | 13 | # Multicluster API concepts 14 | 15 | ![MCS API diagram](../images/mcs-overview.png) 16 | 17 | ### Service and ServiceExport 18 | * Main interaction point for user/administrator with MCS 19 | * A custom resource you can create that marks a Service for export 20 | * The mcs-controller consumes these 21 | Learn more at [ServiceExport](../api-types/service-export.md) 22 | 23 | ### ServiceImport and EndpointSlices 24 | * Created by the mcs-controller in all namespace-same clusters in the ClusterSet 25 | * Representing the imported service and all the available backends for it across the ClusterSet 26 | * Used to create the related EndpointSlices in consuming clusters 27 | Learn more at [ServiceImport](../api-types/service-import.md) -------------------------------------------------------------------------------- /site-src/concepts/namespace-sameness.md: -------------------------------------------------------------------------------- 1 | # Namespace Sameness 2 | 3 | Permissions and characteristics are consistent across clusters for a given namespace. 4 | 5 | Namespaces don't have to exist in every cluster, but behave the same across those in which they do. -------------------------------------------------------------------------------- /site-src/concepts/work-api.md: -------------------------------------------------------------------------------- 1 | # Work API Overview 2 | 3 | A common [Work API](https://github.com/kubernetes-sigs/work-api) to distribute workloads across multiple clusters. 4 | 5 | ![Alt](../images/work-api.png "Work API") 6 | 7 | ## Terminology 8 | 9 | - **Work Hub** is a Kubernetes cluster where the Work API resource resides. 10 | - **Managed Cluster** or Spoke Cluster is a Kubernetes cluster managed by the Work Hub. 11 | The workload resources defined in the Work API are applied on the managed cluster. 12 | - **Work Controller** is a controller that reconciles the Work API resource on Work Hub, 13 | and applies resources defined in the Work to the Managed Cluster. 14 | 15 | 16 | ## Overview 17 | 18 | A Work is a custom resource that represents a list of API resources to be deployed on a cluster. 19 | The Work is created on the Work Hub, and resides in the namespace that the Work Controller is authorized to access. 20 | Creation of a Work on the Work Hub indicates that resources defined in the Work will be applied on a certain Managed Cluster. 21 | Update of a Work will trigger the resource update on the Managed Cluster, and deletion of a Work will garbage collect the resources on the Managed Cluster. 22 | 23 | ## Example 24 | 25 | ```yaml 26 | apiVersion: multicluster.x-k8s.io/v1alpha1 27 | kind: Work 28 | metadata: 29 | name: work-sample 30 | namespace: cluster1 31 | spec: 32 | workload: 33 | manifests: 34 | - apiVersion: v1 35 | kind: ConfigMap 36 | metadata: 37 | name: cm 38 | namespace: default 39 | data: 40 | ui.properties: | 41 | color=purple 42 | ``` 43 | 44 | User creates a Work in the `cluster1` namespace on the Work Hub that the Work Controller is authorized to access. 45 | The Work Controller then accesses the Managed Cluster and applies the resources defined in the Work in its reconcile loop. 46 | The Work controller also tracks the status of applied resources by updating the Work status. 47 | 48 | ## Implementation 49 | 50 | This Work API project solely focuses on the API and the common behaviour, leaving room for various implementations. 51 | There is a reference implementation available in the [GitHub repo](https://github.com/kubernetes-sigs/work-api). 52 | 53 | For more advanced Work API implementations: 54 | 55 | - Open Cluster Management [ManifestWork API](https://open-cluster-management.io/docs/concepts/manifestwork/) 56 | - Karmada [Work API](https://github.com/karmada-io/api/tree/main/work/) 57 | - Azure [Work API](https://github.com/Azure/k8s-work-api) 58 | -------------------------------------------------------------------------------- /site-src/contributing/faq.md: -------------------------------------------------------------------------------- 1 | # Frequently Asked Questions (FAQ) 2 | 3 | * **Q: How can I get involved with Multicluster API?
** 4 | A: The [community](/contributing/community) page keeps track of how to get 5 | involved with the project. 6 | 7 | * **Q: Where can I find Multicluster API releases?
** 8 | A: Multicluster API releases are tags of the [Github repository][1]. 9 | The [Github releases][2] page shows all the releases. 10 | 11 | * **Q: Which Kubernetes versions are supported?
** 12 | A: Generally, the About and Multicluster Services APIs support Kubernetes 1.21+ as the Multicluster API requires support for the [Kubernetes EndpointSlices][3]. 13 | 14 | [1]: https://github.com/kubernetes-sigs/mcs-api 15 | [2]: https://github.com/kubernetes-sigs/mcs-api/releases 16 | [3]: https://kubernetes.io/docs/concepts/services-networking/endpoint-slices/ 17 | -------------------------------------------------------------------------------- /site-src/contributing/index.md: -------------------------------------------------------------------------------- 1 | # How to Get Involved 2 | 3 | This page contains links to all of the meeting notes, design docs and related discussions around the different APIs managed by the Multicluster SIG. 4 | 5 | ## Feedback and Questions 6 | 7 | For general feedback, questions or to share ideas please reach out in [SIG-Multicluster-Slack][slack-channel]. 8 | [slack-channel]:https://kubernetes.slack.com/archives/C09R1PJR3 9 | 10 | ## Bug Reports 11 | 12 | Bug reports should be filed as Github Issues on their respective subproject repo. 13 | 14 | * [Open an issue for a bug with the About API][about-api-issues] 15 | * [Open an issue for a bug with the MCS API][mcs-api-issues] 16 | * [Open an issue for a bug with the Work API][work-api-issues] 17 | * [Open an issue for a bug with the ClusterProfile API][clusterprofile-api-issues] 18 | 19 | **NOTE**: If you're reporting a bug that applies to a specific implementation of 20 | a SIG-MC sponsored API and not the API specification itself, please check our 21 | [implementations page][implementations] to find links to the repositories where 22 | you can get help with your specific implementation. 23 | [about-api-issues]: https://github.com/kubernetes-sigs/about-api/issues 24 | [mcs-api-issues]: https://github.com/kubernetes-sigs/mcs-api/issues 25 | [work-api-issues]: https://github.com/kubernetes-sigs/work-api/issues 26 | [clusterprofile-api-issues]: https://github.com/kubernetes-sigs/cluster-inventory-api/issues 27 | [implementations]: ../guides/index.md 28 | 29 | ## Communications 30 | 31 | Major discussions and notifications will be sent on the [SIG-MC mailing 32 | list][sigmcg]. 33 | 34 | We also have a [Slack channel (sig-multicluster)][slack] on k8s.io for day-to-day questions and discussions. 35 | 36 | [sigmcg]: https://groups.google.com/forum/#!forum/kubernetes-sig-multicluster 37 | [slack]: https://kubernetes.slack.com/archives/C09R1PJR3 38 | 39 | ## Meetings 40 | 41 | Meetings discussing the evolution of the different APIs on SIG-Multicluster happen weekly on Tuesdays at 9:30AM Pacific Time / 18:30 CET. Join kubernetes-sig-multicluster@googlegroups.com to get a calendar invite. 42 | 43 | 44 | 49 | 50 | * [Zoom link](https://zoom.us/my/k8s.mc) 51 | * [Convert to your timezone](http://www.thetimezoneconverter.com/?t=09:30&tz=PT%20%28Pacific%20Time%29) 52 | * [Add to your calendar](https://calendar.google.com/calendar/u/0/r/eventedit/copy/MWlzc3MxZHIzbTM5Zmp0bWlxdDQwM2ZjcG5fMjAyMzAxMjRUMTczMDAwWiBjNWFjODk4NGE2NDIzMGI0YzMwMTEyNGM1MmU1MzMwMDQ0MDI5NjgwNmY2MWEyMmRlNTA3NTk4YTg5YzI4MmVhQGc) 53 | 54 | 55 | ### Meeting Notes and Recordings 56 | 57 | Meeting agendas and notes are maintained in the [meeting notes 58 | doc][meeting-notes]. Feel free to add topics for discussion at an upcoming 59 | meeting. 60 | 61 | All meetings are recorded and automatically uploaded to the [SIG Multicluster meetings Youtube playlist][sig-multicluster-yt-playlist]. 62 | 63 | #### Archived Notes 64 | Some documents from previous quarters were uploaded [here][sig-mc-previous-quarters-docs]. 65 | 66 | [sig-mc-previous-quarters-docs]: https://drive.google.com/open?id=0B6O6mvmXbHiFRE03d0FPSGtTSG8 67 | 68 | #### Initial Design Discussions 69 | 70 | 71 | [sig-multicluster-yt-playlist]: https://www.youtube.com/playlist?list=PL69nYSiGNLP0HqgyqTby6HlDEz7i1mb0- 72 | [sig-net-yt-playlist]: https://www.youtube.com/playlist?list=PL69nYSiGNLP2E8vmnqo5MwPOY25sDWIxb 73 | [early-yt-playlist]: https://www.youtube.com/playlist?list=PL7KjrPTDcs4Xe6SZj-51WvBfufKf-la1O 74 | [kubecon-2019-na-design-discussion]: https://docs.google.com/document/d/1l_SsVPLMBZ7lm_T4u7ZDBceTTUY71-iEQUPWeOdTAxM/preview 75 | [kubecon-2019-eu-discussion]: https://docs.google.com/document/d/1n8AaDiPXyZHTosm1dscWhzpbcZklP3vd11fA6L6ajlY/preview 76 | [sig-net-2019-11-sync]: https://docs.google.com/document/d/1AqBaxNX0uS0fb_fSpVL9c8TmaSP7RYkWO8U_SdJH67k/preview 77 | [meeting-notes]: https://tinyurl.com/sig-multicluster-notes 78 | 79 | ## Presentations and Talks 80 | 81 | [//]: # (Should we move this section in another tab or subtab? Maybe in the 'Reference' section or the 'Blog' section?) 82 | 83 | | Date | Title | | 84 | |----------------|-------|----| 85 | | October, 2022 | [Kubecon NA 2022 Detroit: SIG Multicluster Intro & Deep Dive][2022-kubecon-na-schedule] (AWS-based demo combining About API and their MCS implementation with AWS CloudMap Controller)| [slides][2022-kubecon-na-slides], [video][2022-kubecon-na-video]| 86 | | October, 2022 | [Kubecon NA 2022 Detroit: Multi-Cluster Stateful Set Migration: A solution to Upgrade Pain][2022-kubecon-na-mc-statefulset-schedule] | [slides][2022-kubecon-na-mc-statefulset-slides], [video][2022-kubecon-na-mc-statefulset-video] | 87 | | May, 2022 | [Kubecon EU 2022 Valencia: SIG Multicluster Intro & Deep Dive][2022-kubecon-eu-schedule] (Demo on multicluster plugin for CoreDNS) | [video][2022-kubecon-eu-video] | 88 | | October, 2021 | [Kubecon NA 2021 Los Angeles: SIG Multicluster Intro & Deep Dive][2021-kubecon-na-schedule]] (Explanation of MCS, multicluster DNS)| [slides][2021-kubecon-na-slides], [video][2021-kubecon-na-video] | 89 | | October, 2021 | [Kubecon NA 2021 Los Angeles: Here Be Services: Beyond the Cluster Boundary with Multicluster Services][2021-kubecon-na-here-be-services-schedule] (Demo of MCS on GKE and Submariner.io) | [slides][2021-kubecon-na-here-be-services-slides], [video][2021-kubecon-na-here-be-services] | 90 | | August, 2020 | [Kubecon EU 2020 Virtual : SIG Multicluster Intro][2020-kubecon-eu-schedule] | [video][2020-kubecon-eu-video] | 91 | | November, 2019 | [Kubecon 2019 San Diego: Intro + Deep Dive SIG Multicluster][2019-kubecon-na-schedule] | [slides][2019-kubecon-na-community-slides] | 92 | | May, 2019 | [Kubecon 2019 Barcelona: Ingress V2 and Multicluster Services][2019-kubecon-eu-ingress-v2] | [slides][2019-kubecon-eu-ingress-v2-slides], [video][2019-kubecon-eu-ingress-v2-video]| 93 | | May, 2019 | [Kubecon 2019 Barcelona: Intro + Deep Dive: Multicluster SIG][2019-kubecon-eu-sig-mc-intro] | [video][2019-kubecon-eu-sig-mc-intro-video] 94 | 95 | 96 | [2022-kubecon-na-schedule]: https://sched.co/182P2 97 | [2022-kubecon-na-slides]: https://docs.google.com/presentation/d/106iQ-W3JiyWC_ek6EesisQWhg2bW4xfE514YFAQM3wo/edit?usp=sharing 98 | [2022-kubecon-na-video]: https://www.youtube.com/watch?v=VZnF3YO1cm8 99 | 100 | [2022-kubecon-na-mc-statefulset-schedule]: https://sched.co/182It 101 | [2022-kubecon-na-mc-statefulset-video]: https://www.youtube.com/watch?v=hkyUqgwTZL8 102 | [2022-kubecon-na-mc-statefulset-slides]: https://static.sched.com/hosted_files/kccncna2022/1c/KubeCon%20NA%2722_%20Multi-Cluster%20Stateful%20Set%20Migration_%20A%20Solution%20to%20Upgrade%20Pain.pptx.pdf 103 | 104 | [2022-kubecon-eu-schedule]: https://sched.co/ytq6 105 | [2022-kubecon-eu-video]: https://www.youtube.com/watch?v=cYFxjZEXucM 106 | 107 | [2021-kubecon-na-schedule]: https://sched.co/lV6k 108 | [2021-kubecon-na-slides]: https://static.sched.com/hosted_files/kccncna2021/d4/SIG%20Multicluster%20Intro%20%26%20Deep%20Dive%20KubeCon%20NA%202021-final.pdf 109 | 110 | [2021-kubecon-na-video]: https://www.youtube.com/watch?v=zVTFm7HJD3s 111 | [2021-kubecon-na-here-be-services-schedule]: https://sched.co/lV67 112 | [2021-kubecon-na-here-be-services-slides]: https://static.sched.com/hosted_files/kccncna2021/5b/Here%20Be%20Services.pdf 113 | [2021-kubecon-na-here-be-services]: https://www.youtube.com/watch?v=_UJrSfmvlMA 114 | 115 | [2020-kubecon-eu-schedule]: https://sched.co/Zew0 116 | [2020-kubecon-eu-video]: https://www.youtube.com/watch?v=bv9c1lJxDIo 117 | 118 | [2019-kubecon-na-schedule]: https://sched.co/Uakw 119 | [2019-kubecon-na-slides]: https://static.sched.com/hosted_files/kccncna19/29/SIG%20Multicluster%20KubeCon%20NA%202019%282%29.pdf 120 | 121 | [2019-kubecon-na-video]: https://www.youtube.com/watch?v=cduG0FrjdJA 122 | 123 | [2019-kubecon-eu-ingress-v2]: https://kccnceu19.sched.com/event/MPb6/ingress-v2-and-multicluster-services-rohit-ramkumar-bowei-du-google 124 | [2019-kubecon-eu-ingress-v2-slides]: https://static.sched.com/hosted_files/kccnceu19/97/%5Bwith%20speaker%20notes%5D%20Kubecon%20EU%202019_%20Ingress%20V2%20%26%20Multi-Cluster%20Services.pdf 125 | [2019-kubecon-eu-ingress-v2-video]: https://www.youtube.com/watch?v=Ne9UJL6irXY&t=1s 126 | 127 | [2019-kubecon-eu-sig-mc-intro]: https://sched.co/MPlP 128 | [2019-kubecon-eu-sig-mc-intro-video]: https://www.youtube.com/watch?v=GOiN1R2vQos 129 | 130 | [2019-kubecon-na-community-slides]: https://docs.google.com/presentation/d/1s0scrQCCFLJMVjjGXGQHoV6_4OIZkaIGjwj4wpUUJ7M 131 | 132 | ## Code of conduct 133 | 134 | Participation in the Kubernetes community is governed by the [Kubernetes Code of 135 | Conduct](https://github.com/kubernetes/community/blob/master/code-of-conduct.md) 136 | -------------------------------------------------------------------------------- /site-src/guides/coredns.md: -------------------------------------------------------------------------------- 1 | # Configuring CoreDNS with the multicluster option 2 | 3 | There is a ready made [CoreDNS multicluster plugin](https://coredns.io/explugins/multicluster/) you can use as the DNS component against MCS API implementations using EndpointSlices. By default, [CoreDNS](https://coredns.io/) does not include this plugin and it is therefore necessary to recompile CoreDNS to build a container image enabling this functionality. 4 | The following paragraphs highlight how one can re-deploy CoreDNS with the [multicluster plugin](https://coredns.io/explugins/multicluster/). To illustrate the concepts, it has been chosen to use a Kind cluster with its default configuration. 5 | 6 | ## Step 1: Deploying a Kind cluster and checking its CoreDNS configuration 7 | 8 | Kind provides an easy way to deploy a small cluster locally on your computer. To do so, you only need to deploy the kind CLI, and type: 9 | 10 | ``` 11 | kind create cluster --name cluster-1 12 | ``` 13 | 14 | **Output (Do Not Copy)** 15 | ``` 16 | Creating cluster "cluster-1" ... 17 | ✓ Ensuring node image (kindest/node:v1.25.3) 🖼 18 | ✓ Preparing nodes 📦 19 | ✓ Writing configuration 📜 20 | ✓ Starting control-plane 🕹️ 21 | ✓ Installing CNI 🔌 22 | ✓ Installing StorageClass 💾 23 | Set kubectl context to "kind-cluster-1" 24 | You can now use your cluster with: 25 | 26 | kubectl cluster-info --context kind-cluster-1 27 | 28 | Not sure what to do next? 😅 Check out https://kind.sigs.k8s.io/docs/user/quick-start/ 29 | ``` 30 | 31 | You can then verify that CoreDNS is indeed well deployed: 32 | 33 | ``` 34 | kubectl get pods -n kube-system | grep coredns 35 | ``` 36 | **Output (Do Not Copy)** 37 | ``` 38 | coredns-565d847f94-brvlb 1/1 Running 0 5m20s 39 | coredns-565d847f94-zzdrd 1/1 Running 0 5m20s 40 | ``` 41 | 42 | Before proceding with the re-compilation of CoreDNS, let's retrieve its current configuration by executing the command `coredns -plugins` in one of those pods. 43 | 44 | ``` 45 | kubectl exec -ti coredns-565d847f94-brvlb -n kube-system -- /coredns -plugins 46 | ``` 47 | **Output (Do Not Copy)** 48 | ``` 49 | Server types: 50 | dns 51 | 52 | Caddyfile loaders: 53 | flag 54 | default 55 | 56 | Other plugins: 57 | dns.acl 58 | dns.any 59 | dns.auto 60 | dns.autopath 61 | dns.azure 62 | dns.bind 63 | dns.bufsize 64 | dns.cache 65 | dns.cancel 66 | dns.chaos 67 | dns.clouddns 68 | dns.debug 69 | dns.dns64 70 | dns.dnssec 71 | dns.dnstap 72 | dns.erratic 73 | dns.errors 74 | dns.etcd 75 | dns.file 76 | dns.forward 77 | dns.geoip 78 | dns.grpc 79 | dns.header 80 | dns.health 81 | dns.hosts 82 | dns.k8s_external 83 | dns.kubernetes 84 | dns.loadbalance 85 | dns.local 86 | dns.log 87 | dns.loop 88 | dns.metadata 89 | dns.minimal 90 | dns.nsid 91 | dns.pprof 92 | dns.prometheus 93 | dns.ready 94 | dns.reload 95 | dns.rewrite 96 | dns.root 97 | dns.route53 98 | dns.secondary 99 | dns.sign 100 | dns.template 101 | dns.tls 102 | dns.trace 103 | dns.transfer 104 | dns.whoami 105 | on 106 | ``` 107 | 108 | This list is important as we will use it and just add the multicluster plugin to recompile CoreDNS. 109 | 110 | ## Re-compiling CoreDNS 111 | The easiest way to recompile CoreDNS and generate a new container image is to use the instructions on the [official CoreDNS source repository](https://github.com/coredns/coredns#compilation-from-source). We specifically recommend the compilation with Docker which includes a ready-to-use Go environment. 112 | 113 | Prior to triggering the compilation, it is necessary to modify the `plugin.cfg` file. First, it is highly recommended to keep the same plugins as the ones found in the previous paragraph. 114 | Second, it is necessary to add the following instruction right **after** the `kubernetes:kubernetes` line: 115 | ``` 116 | ... 117 | kubernetes:kubernetes 118 | multicluster:github.com/coredns/multicluster 119 | ... 120 | ``` 121 | Then trigger the recompilation: 122 | 123 | ``` 124 | $ docker run --rm -i -t -v $PWD:/v -w /v golang:1.18 make 125 | ``` 126 | 127 | Once you have recompiled CoreDNS with the multicluster plugin, you can then build the new container image. 128 | 129 | ``` 130 | sudo docker buildx build --platform linux/amd64 . -t [your-image-registry-path]:with-mcs-plugin 131 | ``` 132 | 133 | Then push the image to your registry. 134 | 135 | ``` 136 | docker push [your-image-registry-path]:with-mcs-plugin 137 | ``` 138 | 139 | ## Deploying the multicluster-enabled CoreDNS image 140 | The new CoreDNS with multicluster plugin enabled is now ready to be deployed. However, this new component will require some extra RBAC roles in order to query the Kubernetes API to discover ServiceImport objects, and a modification of its configuration file (Corefile) stored in the `coredns` ConfigMap object. 141 | 142 | ### Deploy the Multicluster-related CRDs 143 | 144 | ``` 145 | kubectl apply -f https://github.com/kubernetes-sigs/mcs-api/blob/master/config/crd/multicluster.x-k8s.io_serviceexports.yaml 146 | kubectl apply -f https://github.com/kubernetes-sigs/mcs-api/blob/master/config/crd/multicluster.x-k8s.io_serviceimports.yaml 147 | ``` 148 | 149 | ### Setting up RBAC roles for CoreDNS 150 | Create a new ClusterRole and bind it to the `coredns` Service Account. 151 | 152 | ``` 153 | cat < coredns-multicluster-rbac.yaml 154 | apiVersion: rbac.authorization.k8s.io/v1 155 | kind: ClusterRole 156 | metadata: 157 | name: system:coredns-multicluster 158 | rules: 159 | - apiGroups: 160 | - "multicluster.x-k8s.io" 161 | resources: 162 | - serviceimports 163 | verbs: ["*"] 164 | --- 165 | apiVersion: rbac.authorization.k8s.io/v1 166 | kind: ClusterRoleBinding 167 | metadata: 168 | name: system:coredns-multicluster 169 | roleRef: 170 | apiGroup: rbac.authorization.k8s.io 171 | kind: ClusterRole 172 | name: system:coredns-multicluster 173 | subjects: 174 | - kind: ServiceAccount 175 | name: coredns 176 | namespace: kube-system 177 | EOF 178 | ``` 179 | then apply the manifest. 180 | 181 | ``` 182 | kubectl apply -f ./coredns-multicluster-rbac.yaml 183 | ``` 184 | 185 | ### Update the ConfigMap with the CoreDNS Corefile 186 | The CoreDNS Corefile includes the configuration of CoreDNS running on the cluster. 187 | 188 | You need to edit the ConfigMap to add the `multicluster clusterset.local` line before the `kubernetes cluster.local...` line. 189 | 190 | ``` 191 | ... 192 | multicluster clusterset.local 193 | kubernetes cluster.local in-addr.arpa ip6.arpa { 194 | pods insecure 195 | fallthrough in-addr.arpa ip6.arpa 196 | ttl 30 197 | } 198 | ... 199 | ``` 200 | 201 | then perform a `rollout restart` of the `coredns` deployment so that CoreDNS can take this new configuration into account. 202 | 203 | ``` 204 | kubectl rollout restart deploy coredns -n kube-system 205 | ``` 206 | 207 | ### Re-deploy CoreDNS 208 | Save the current configuration of the CoreDNS deployment, and delete it from the cluster. 209 | 210 | ``` 211 | kubectl get deploy coredns -n kube-system -o yaml > coredns-deploy.yaml 212 | kubectl delete deploy coredns 213 | ``` 214 | 215 | Replace the image path in the deployment manifest with the one you previously pushed to your image registry, and re-deploy the manifest. The new pods will restart with the new configuration stored in the Config Map previously modified. 216 | 217 | ### Verify that CoreDNS is healthy 218 | 219 | ``` 220 | kubectl get pods -n kube-system 221 | ``` 222 | 223 | **Output (Do Not Copy)** 224 | ``` 225 | kubectl get pods -n kube-system 226 | NAME READY STATUS RESTARTS AGE 227 | coredns-55fcfcb54f-lg25c 1/1 Running 0 25s 228 | coredns-55fcfcb54f-ts9sp 1/1 Running 0 25s 229 | etcd-cluster-1-control-plane 1/1 Running 0 38m 230 | kindnet-wd847 1/1 Running 0 38m 231 | kube-apiserver-cluster-1-control-plane 1/1 Running 0 39m 232 | kube-controller-manager-cluster-1-control-plane 1/1 Running 0 38m 233 | kube-proxy-n9ds4 1/1 Running 0 38m 234 | kube-scheduler-cluster-1-control-plane 1/1 Running 0 39m 235 | ``` 236 | 237 | ## More steps when you want to check that the multicluster plugin works 238 | 239 | Create a demo namespace and deploy a fake ServiceImport. 240 | 241 | ``` 242 | cat < demo-service-import.yaml 243 | apiVersion: multicluster.x-k8s.io/v1alpha1 244 | kind: ServiceImport 245 | metadata: 246 | name: myservice 247 | namespace: demo 248 | spec: 249 | type: ClusterSetIP 250 | ips: 251 | - 1.2.3.4 252 | ports: 253 | - port: 80 254 | protocol: TCP 255 | EOF 256 | ``` 257 | ``` 258 | kubectl apply -f demo-service-import.yaml 259 | ``` 260 | 261 | Then deploy a `dnsutils` pod in the demo namespace. 262 | 263 | ``` 264 | cat < dnsutils.yaml 265 | apiVersion: v1 266 | kind: Pod 267 | metadata: 268 | name: dnsutils 269 | namespace: demo 270 | spec: 271 | containers: 272 | - name: dnsutils 273 | image: k8s.gcr.io/e2e-test-images/jessie-dnsutils:1.3 274 | command: 275 | - sleep 276 | - "3600" 277 | imagePullPolicy: IfNotPresent 278 | restartPolicy: Always 279 | EOF 280 | ``` 281 | 282 | ``` 283 | kubectl apply -f dnsutils.yaml 284 | ``` 285 | 286 | You can then use the `dnsutils` pod to confirm that the DNS query for the ServiceImport responds with the IP set in the fake ServiceImport previously defined. 287 | 288 | ``` 289 | kubectl exec -it dnsutils -n demo -- bash 290 | ``` 291 | ``` 292 | root@dnsutils:/# nslookup myservice.demo.svc.clusterset.local 293 | ``` 294 | **Output (Do Not Copy)** 295 | ``` 296 | Server: 10.96.0.10 297 | Address: 10.96.0.10#53 298 | 299 | Name: myservice.demo.svc.clusterset.local 300 | Address: 1.2.3.4 301 | ``` -------------------------------------------------------------------------------- /site-src/guides/gateway-api.md: -------------------------------------------------------------------------------- 1 | # Multicluster API support in Gateway API -------------------------------------------------------------------------------- /site-src/guides/gke-mcs.md: -------------------------------------------------------------------------------- 1 | # Getting started with GKE Multicluster Services -------------------------------------------------------------------------------- /site-src/guides/guidelines.md: -------------------------------------------------------------------------------- 1 | # Implementation guidelines 2 | 3 | There are some general guidelines for implementers of SIG-Multicluster sponsored 4 | APIs. 5 | 6 | 7 | ## Conformance Expectations 8 | 9 | We expect there will be varying levels of conformance among the different 10 | providers for some time. SIG-Multicluster is currently working on the framework 11 | for a conformance suite so implementations can test their conformance to the API 12 | specifications in an automated way. For now, each individual KEP indicates what 13 | a conformant implementation of a given API "MUST", "MAY", and "SHOULD" adhere 14 | to, following the interpretations of those terms as described in RFC 2119. 15 | 16 | 17 | ### Implementation-specific 18 | 19 | In some aspects of the APIs, the specification provides the general user usage 20 | pattern of a feature, however, the exact behavior may depend on the underlying 21 | implementation. When known, these are called out in the KEP as implementation 22 | details to clearly distinguish between conformance expectations and the 23 | variations in behavior that are considered "implementation-specific". 24 | 25 | 26 | ## API Conventions 27 | 28 | SIG-Multicluter sponsored APIs follow Kubernetes API [conventions]. These 29 | conventions are intended to ease client development and ensure that 30 | configuration mechanisms can consistently be implemented across a diverse set of 31 | use cases. 32 | 33 | [conventions]:(https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md) 34 | 35 | 36 | ## API Process 37 | 38 | SIG-Multicluster sponsored APIs are communicated and matured via the [Kubernetes 39 | Enhancements Proposal process][KEPs], regardless of whether they are implemented as 40 | part of a Kubernetes release. SIG-sponsored artifacts such as conformance tests, 41 | published CRD yaml, or related images or software are published in repos in the 42 | [Kubernetes-sigs Github organization][kubernetes-sigs]. 43 | 44 | [KEPs]: (https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster) 45 | [kubernetes-sigs]: (https://github.com/kubernetes-sigs/) 46 | 47 | ## Limitations of CRD and Webhook Validation 48 | 49 | CRD and webhook validation is not the final validation i.e. webhook is "nice UX" 50 | but not schema enforcement. This validation is intended to provide immediate 51 | feedback to users when they provide an invalid configuration. Write code 52 | defensively with the assumption that at least some invalid input will reach your 53 | controller. Both Webhook and CRD validation is not fully reliable because it: 54 | 55 | * May not be deployed correctly. 56 | * May be loosened in future API releases. (Fields may contain values with less 57 | restrictive validation in newer versions of the API). 58 | 59 | *Note: These limitations are not unique to SIG-Multicluster sponsored APIs and 60 | apply more broadly to any Kubernetes CRDs and webhooks.* 61 | 62 | Implementers should ensure that, even if unexpected values are encountered in 63 | the API, their implementations are still as secure as possible and handle this 64 | input gracefully. The most common response would be to reject the configuration 65 | as malformed and signal the user via a condition in the status block. To avoid 66 | duplicating work, Multicluster API maintainers are considering adding a shared 67 | validation package that implementations can use for this purpose. 68 | -------------------------------------------------------------------------------- /site-src/guides/index.md: -------------------------------------------------------------------------------- 1 | # Implementations 2 | 3 | This document tracks downstream implementations and integrations of Multicluster API and provides status and resource references for them. 4 | 5 | Implementors and integrators of Multicluster API are encouraged to update this document with status information about their implementations, the versions they cover, and documentation to help users get started. 6 | 7 | ## Implementation Status 8 | 9 | - [Google Cloud MCS][gke-mcs]: General Availability 10 | - [Submariner][submariner]: 0.13.3 11 | - [MCS controller for AWS Cloudmap][aws-mcs]: Alpha 12 | - [Antrea Multi-cluster][antrea-mcs]: Alpha 13 | - [Cilium Cluster Mesh][cilium-clustermesh]: Beta (from Cilium v1.17) 14 | 15 | ## Implementations 16 | 17 | In this section you will find specific links to blog posts, documentation and other Multicluster API references for specific implementations. 18 | 19 | 20 | ### Google Kubernetes Engine 21 | 22 | [Google Kubernetes Engine (GKE)][gke] is a managed Kubernetes platform offered by Google Cloud. GKE's implementation of the Multicluster API is through the [GKE Multi Cluster Service][gke-mcs]. 23 | 24 | [gke]:https://cloud.google.com/kubernetes-engine 25 | [gke-mcs]:https://cloud.google.com/kubernetes-engine/docs/concepts/multi-cluster-services 26 | 27 | Please follow this [guide][gke-mcs-guide] for the first steps to set up multicluster services on GKE. 28 | 29 | [gke-mcs-guide]:gke-mcs.md 30 | 31 | ### Submariner 32 | 33 | [Submariner][submariner] is an open-source project enabling direct networking between Pods and Services in different Kubernetes clusters, either on-premises or in the cloud. 34 | Submariner provides: 35 | 36 | - Cross-cluster L3 connectivity using encrypted and unencrypted connections 37 | - Service Discovery across clusters 38 | - `subctl`, a command-line utility that simplifies deployment and management 39 | - Support for interconnecting clusters using overlapping CIDRs 40 | 41 | [submariner]: https://submariner.io/ 42 | 43 | ### MCS controller for AWS Cloudmap 44 | The [AWS Cloud Map Multi-cluster Service Discovery Controller for Kubernetes (K8s)][aws-mcs] implements the Kubernetes [KEP-1645: Multi-Cluster Services API][kep-1645] and [KEP-2149: ClusterId for ClusterSet identification][kep-2149], which allows services to communicate across multiple clusters. The implementation relies on AWS Cloud Map for enabling cross-cluster service discovery. 45 | 46 | Please follow this [guide][aws-mcs-guide] for the first steps to set up the multicluster controller. 47 | 48 | [aws-mcs]: https://github.com/aws/aws-cloud-map-mcs-controller-for-k8s 49 | [aws-mcs-guide]: https://aws.github.io/aws-cloud-map-mcs-controller-for-k8s/ 50 | [kep-1645]: https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/1645-multi-cluster-services-api 51 | [kep-2149]: https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/2149-clusterid 52 | 53 | ### Antrea Multi-cluster 54 | 55 | [Antrea][antrea] is an open-source project which is a Kubernetes networking solution intended to be Kubernetes native. It operates at Layer 3/4 to provide networking and security services for a Kubernetes cluster, leveraging Open vSwitch as the networking data plane. 56 | 57 | [Antrea Multi-cluster][antrea-mcs-arch] implements Multi-cluster Service API, which allows users to create multi-cluster Services that can be accessed cross clusters in a ClusterSet. Antrea Multi-cluster also extends Antrea native NetworkPolicy to support [Multi-cluster NetworkPolicy][antrea-mcs-anp] rules that apply to cross-cluster traffic, and [ClusterNetworkPolicy replication][antrea-mcs-cnp-replica] that allows a ClusterSet admin to create ClusterNetworkPolicies which are replicated across the entire ClusterSet and enforced in all member clusters. 58 | 59 | Please follow this [guide][antrea-mcs-user-guide] for the first steps to set up Antrea Multi-cluster. 60 | 61 | [antrea]: https://antrea.io/ 62 | [antrea-mcs]: https://github.com/antrea-io/antrea/tree/main/multicluster 63 | [antrea-mcs-arch]: https://github.com/antrea-io/antrea/blob/main/docs/multicluster/architecture.md 64 | [antrea-mcs-cnp-replica]: https://github.com/antrea-io/antrea/blob/main/docs/multicluster/user-guide.md#clusternetworkpolicy-replication 65 | [antrea-mcs-anp]: https://github.com/antrea-io/antrea/blob/main/docs/multicluster/user-guide.md#multi-cluster-networkpolicy 66 | [antrea-mcs-user-guide]: https://github.com/antrea-io/antrea/blob/main/docs/multicluster/user-guide.md 67 | 68 | ### Cilium Cluster Mesh 69 | 70 | [Cilium][cilium] is an open source, cloud native solution for providing, securing, and observing network connectivity between workloads, fueled by the Kernel technology eBPF. 71 | 72 | [Cilium Cluster Mesh][cilium-clustermesh] allows you to connect the networks of multiple clusters in such as way that pods in each cluster can discover and access services in all other clusters of the mesh, provided all the clusters run Cilium as their CNI. This allows effectively joining multiple clusters into a large unified network, regardless of the Kubernetes distribution or location each of them is running. 73 | 74 | Starting with Cilium version 1.17, Cilium Cluster Mesh also supports MCS-API; see the corresponding [guide][cilium-mcs] for more information! 75 | 76 | [cilium]: https://cilium.io/ 77 | [cilium-clustermesh]: https://cilium.io/use-cases/cluster-mesh/ 78 | [cilium-mcs]: https://docs.cilium.io/en/stable/network/clustermesh/mcsapi/ 79 | -------------------------------------------------------------------------------- /site-src/guides/istio.md: -------------------------------------------------------------------------------- 1 | # Multicluster API support in Istio -------------------------------------------------------------------------------- /site-src/guides/submariner-mcs.md: -------------------------------------------------------------------------------- 1 | # Getting started with Submariner Multicluster Services -------------------------------------------------------------------------------- /site-src/images/about-api.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kubernetes-sigs/sig-multicluster-site/46de6540db4b1965ffbc6a6ebe9bb9712e554416/site-src/images/about-api.png -------------------------------------------------------------------------------- /site-src/images/cluster-profile-api.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kubernetes-sigs/sig-multicluster-site/46de6540db4b1965ffbc6a6ebe9bb9712e554416/site-src/images/cluster-profile-api.png -------------------------------------------------------------------------------- /site-src/images/k8s-favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kubernetes-sigs/sig-multicluster-site/46de6540db4b1965ffbc6a6ebe9bb9712e554416/site-src/images/k8s-favicon.png -------------------------------------------------------------------------------- /site-src/images/mcs-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kubernetes-sigs/sig-multicluster-site/46de6540db4b1965ffbc6a6ebe9bb9712e554416/site-src/images/mcs-overview.png -------------------------------------------------------------------------------- /site-src/images/prepopulated-snippet.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kubernetes-sigs/sig-multicluster-site/46de6540db4b1965ffbc6a6ebe9bb9712e554416/site-src/images/prepopulated-snippet.png -------------------------------------------------------------------------------- /site-src/images/snippet-selection.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kubernetes-sigs/sig-multicluster-site/46de6540db4b1965ffbc6a6ebe9bb9712e554416/site-src/images/snippet-selection.png -------------------------------------------------------------------------------- /site-src/images/work-api.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kubernetes-sigs/sig-multicluster-site/46de6540db4b1965ffbc6a6ebe9bb9712e554416/site-src/images/work-api.png -------------------------------------------------------------------------------- /site-src/index.md: -------------------------------------------------------------------------------- 1 | # Introduction 2 | 3 | Since its inception in 2015, Kubernetes has been pretty successful at popularizing the idea of container clusters. Adoption has reached the point that many users are deploying their applications across multiple clusters and are struggling to make it work smoothly. 4 | 5 | SIG-Multicluster is a [Special Interest Group][sig-multicluster-github] focused on solving common challenges related to the management of multiple Kubernetes clusters, and applications that exist therein. 6 | 7 | Specifically, the SIG aims to find Kubernetes-native ways to: 8 | 9 | * Expose workloads from multiple clusters to each other 10 | * Share cluster metadata and its place relative to others 11 | * Generally break down the walls between clusters 12 | 13 | The SIG is responsible for designing, discussing, implementing and maintaining APIs, tools and documentation related to multi-cluster administration and application management. This includes not only active automated approaches such as Cluster Federation, but also those that employ batch workflow-style continuous deployment systems like Spinnaker and others. Standalone building blocks for these and other similar systems (for example a cluster registry), and proposed changes to kubernetes core where appropriate will also be in scope. 14 | 15 | ## Problem statement: why multicluster? 16 | 17 | There are many reasons to want to run multiple clusters, including but not limited to: 18 | 19 | * Location 20 | * Latency: it can be necessary to deploy the application as close to the customers as possible. 21 | * Jurisdiction: it can be mandated to keep user data in-country. 22 | * Data gravity: data already exists in one provider, but it can be decided to run the application in another environment. 23 | 24 | * Isolation 25 | * Environment (e.g. dev, test, prod) 26 | * Performance isolation: a workload may consume too many resources, at the expense of other workloads. 27 | * Security isolation: sensitive data or untrusted code must be isolated in their own environments. 28 | * Organizational isolation: teams may have different management domains. 29 | * Cost isolation: multitenancy can greatly complexify billing management for different teams. 30 | 31 | * Reliability 32 | * Blast radius: an infrastructure or application incident in one cluster must not impact the whole system. 33 | * Infrastructure diversity: an underlying zone, region, or provider outage does not bring down the whole system. 34 | * Scale: the application is too big to fit in a single cluster. 35 | * Upgrade scope: some parts of the application may require an infrastructure upgrade, that may impact other parts of the application. Having multiple clusters can also avoid the need for in-place cluster upgrades. 36 | 37 | ## Project charter 38 | The following charter defines the scope and governance of the [Multicluster Special Interest Group][sig-multicluster-github]: 39 | 40 | * Support an out-of-tree ecosystem by defining API standards that leave plenty of room for flexibility in their ultimately third party implementation. 41 | 42 | * Protect the known multicluster experience from incompatible changes upstream to single clusters by working with other [SIGs][sigs-github]. 43 | 44 | * Advocate and provide feedback on proposals for extending the single cluster experience to multicluster i.e. network policy. 45 | 46 | [sig-multicluster-github]: https://github.com/kubernetes/community/tree/master/sig-multicluster 47 | [sigs-github]: https://github.com/kubernetes-sigs 48 | 49 | 50 | 51 | ## Approach 52 | 53 | To meet the goals listed above, the SIG-Multicluster team has worked to define four different APIs: 54 | 55 | * [About API][about-api-reference]: allows to uniquely identify clusters within a set of clusters ([clusterset][clusterset-definition]) 56 | * [Multicluster Services API][mc-api-reference]: allows to expose services across clusters which are part of a given [clusterset][clusterset-definition]. 57 | * [Work API][work-api-reference]: allows to define the workloads to be deployed across clusters which are part of a given [clusterset][clusterset-definition]. 58 | * [ClusterProfile API][clusterprofile-reference]: simplifies the discovery and management of clusters, offering a comprehensive status overview for both applications and human operators. 59 | 60 | [about-api-reference]: ./concepts/about-api.md 61 | [mc-api-reference]: ./concepts/multicluster-services-api.md 62 | [work-api-reference]: ./concepts/work-api.md 63 | [clusterset-definition]: ./api-types/cluster-set.md 64 | [clusterprofile-reference]: ./concepts/cluster-profile-api.md 65 | 66 | To leave room for implementation, SIG-Multicluster does not focus on the implementation of the mechanisms that rely on those APIs. For example, no reference implementation is provided for a cluster registry or for service discovery itself. 67 | 68 | # Getting started 69 | Whether you are a user interested in using the different APIs or an implementer interested in conforming to the APIs, the following resources will help give you the necessary background: 70 | 71 | * [KubeCon NA 2022 "SIG-Multicluster Intro and Deep Dive"][kubecon-na-2022-video] by Laura Lorenz (Google), Jeremy Olmsted-Thompson (Google) and Paul Morie (Apple) 72 | 73 | [![Watch the video](https://img.youtube.com/vi/VZnF3YO1cm8/hqdefault.jpg)](https://www.youtube.com/watch?v=VZnF3YO1cm8) 74 | 75 | * [Implementation guide and references][implementation-index] 76 | 77 | [kubecon-na-2022-video]: https://www.youtube.com/watch?v=VZnF3YO1cm8 78 | [implementation-index]: ./guides/index.md 79 | 80 | * [Community links][get-involved] 81 | 82 | # Contributing 83 | If you are interested in contributing to SIG-Multicluster or building an implementation of one of our APIs, then don’t hesitate to [get involved][get-involved] in SIG meetings, issues on projects, or new designs. 84 | 85 | [get-involved]: ./contributing/index.md 86 | 87 | ## Read the KEPs! 88 | 89 | !!!note 90 | Read more about the [Kubernetes Enhancement Proposal](https://github.com/kubernetes/enhancements/blob/master/keps/README.md) 91 | 92 | * You can check out all of the sig keps at the [sig-multicluster KEP home](https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster) 93 | 94 | * [2149-clusterid](https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/2149-clusterid) 95 | * [4322-cluster-inventory](https://github.com/kubernetes/enhancements/blob/master/keps/sig-multicluster/4322-cluster-inventory/README.md) 96 | * [1645-multi-cluster-service-api](https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/1645-multi-cluster-services-api) 97 | -------------------------------------------------------------------------------- /site-src/references/README.md: -------------------------------------------------------------------------------- 1 | # Snippets for Visual Studio Code 2 | The file [yaml.json](./yaml.json) in this folder can be appended to your Visual Studio Code user configuration YAML edition preferences `(\${HOME}/.config/Code/\${USER}/yaml.json)` to enable a simplified experience when writing MCS-related manifests. 3 | > As the yaml.json contains all personalized snippets, it is recommended to append the contents and not copy over the file. 4 | 5 | Once the snippets are copied over, create a new YAML file, and press `CTRL + Space`, and you should see a list of snippets available. 6 | 7 | ![Snippets drop-down selection in VSCode](../images/snippet-selection.png) 8 | 9 | 10 | If you select, say for example, the ServiceImport snippet, your file will be pre-filled with the corresponding snippet. Using the tab key, you can navigate easily between the different values that you may want to change. 11 | 12 | ![Pre-populated snippet in VSCode](../images/prepopulated-snippet.png) -------------------------------------------------------------------------------- /site-src/references/spec.md: -------------------------------------------------------------------------------- 1 | TBD 2 | -------------------------------------------------------------------------------- /site-src/references/yaml.json: -------------------------------------------------------------------------------- 1 | { 2 | "Work": { 3 | "prefix": ["Work"], 4 | "body": [ 5 | "apiVersion: multicluster.x-k8s.io/v1alpha1", 6 | "kind: Work", 7 | "metadata:", 8 | "\tname: ${1:work-name}", 9 | "\tnamespace: ${2:cluster-name}", 10 | "spec:", 11 | "\tworkload:", 12 | "\t\tmanifests:", 13 | "\t\t- apiVersion: v1", 14 | "\t\t kind: $3", 15 | "\t\t metadata: $4", 16 | "\t\t namespace: $5" 17 | ], 18 | "description": "Work object as described in the Work API (https://github.com/kubernetes-sigs/work-api)" 19 | }, 20 | "ServiceImport": { 21 | "prefix": ["ServiceImport"], 22 | "body": [ 23 | "apiVersion: multicluster.x-k8s.io/v1alpha1", 24 | "kind: ServiceImport", 25 | "metadata:", 26 | "\tname: ${1:service-name}", 27 | "\tnamespace: ${2:demo}", 28 | "spec:", 29 | "\ttype: ${3:ClusterSetIP}", 30 | "\tips:", 31 | "\t- ${4:1.2.3.4}", 32 | "\tports:", 33 | "\t- name: ${5:http}", 34 | "\t protocol: TCP", 35 | "\t port: ${6:80}" 36 | ], 37 | "description": "ServiceImport object as described in the Multicluster API (https://github.com/kubernetes-sigs/mcs-api/)" 38 | }, 39 | "ServiceExport": { 40 | "prefix": ["ServiceExport"], 41 | "body": [ 42 | "apiVersion: multicluster.x-k8s.io/v1alpha1", 43 | "kind: ServiceExport", 44 | "metadata:", 45 | "\tname: ${1:service-name}", 46 | "\tnamespace: ${2:demo}" 47 | ], 48 | "description": "ServiceImport object as described in the Multicluster API (https://github.com/kubernetes-sigs/mcs-api/)" 49 | }, 50 | "EndPointSlice": { 51 | "prefix": ["EndPointSlice"], 52 | "body": [ 53 | "apiVersion: discovery.k8s.io/v1beta1", 54 | "kind: EndPointSlice", 55 | "metadata:", 56 | "\tname: ${1:imported-service-cluster-name}", 57 | "\tnamespace: ${2:demo}", 58 | "\tlabels:", 59 | "\t\tmulticluster.kubernetes.io/source-cluster: us-west2-a-my-cluster", 60 | "\t\tmulticluster.kubernetes.io/service-name: my-svc", 61 | "\townerReferences:", 62 | "\t- apiVersion: multicluster.k8s.io/v1alpha1", 63 | "\t controller: false", 64 | "\t kind: ServiceImport", 65 | "\t name: my-svc", 66 | "addressType: ${3:IPv4}", 67 | "ports:", 68 | "\t- name: http", 69 | "\t protocol: TCP", 70 | "\t port: ${4:80}", 71 | "endpoints:", 72 | "\t- addresses:", 73 | "\t\t- ${5:10.1.2.3}", 74 | "\t conditions:", 75 | "\t\t ready: true", 76 | "\t hostname: ${6:pod-1}", 77 | "\t nodeName: ${7:node-1}", 78 | "\t zone: ${8:us-west2-a}" 79 | ], 80 | "description": "EndPointSlice object as described in https://kubernetes.io/docs/concepts/services-networking/endpoint-slices/" 81 | }, 82 | "ClusterSet (About API)": { 83 | "prefix": ["ClusterSet"], 84 | "body": [ 85 | "apiVersion: about.k8s.io/v1", 86 | "kind: ClusterProperty", 87 | "metadata:", 88 | "\tname: clusterset.k8s.io", 89 | "spec:", 90 | "\tvalue: ${1:clusterset-1}" 91 | ], 92 | "description": "ClusterSet object as described in the About API (https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/2149-clusterid)" 93 | }, 94 | "Cluster (About API)": { 95 | "prefix": ["Cluster"], 96 | "body": [ 97 | "apiVersion: about.k8s.io/v1", 98 | "kind: ClusterProperty", 99 | "metadata:", 100 | "\tname: cluster.clusterset.k8s.io", 101 | "spec:", 102 | "\tvalue: ${1:cluster-1}" 103 | ], 104 | "description": "Cluster object as described in the About API (https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/2149-clusterid)" 105 | } 106 | 107 | } --------------------------------------------------------------------------------