لایب سان

6 The Kubernetes API Verbs are mapped directly to the operations in the OpenAPI specification. The defined verbs are get, create, update, patch, delete, list, watch, and deletecollection. The correspondence with the HTTP verbs can be found in Table 1-1. Table 1-1. Correspondence Between Kubernetes API Verbs and HTTP Verbs Kubernetes API Verb HTTP Verb get Get create post update put patch patCh delete deLete list Get watch Get deletecollection deLete The Kubernetes Kinds are a subset of the definitions in the OpenAPI specification. When requests are made to the Kubernetes API, data structures are exchanged through the bodies of requests and responses. These structures share common fields, apiVersion and kind, to help the participants of the request recognize these structures. If you wanted to make your User API manage this Kind concept, the User structure would contain two additional fields, apiVersion and kind—for example, with values v1 and User. To determine whether a definition in the Kubernetes OpenAPI specification is a Kubernetes Kind, you can look at the x-kubernetes-group-version-kind field of the definition. If this field is defined, the definition is a kind, and it gives you the values of the apiVersion and kind fields. Group-Version-Resource The Kubernetes API is a REST API, and as a result of that it manages Resources, and the paths to manage these resources follow the REST naming conventions—that is, by using a plural name to identify a resource and by grouping these resources. Chapter 1 Kubernetes apI IntroduCtIon 7 Because the Kubernetes API manages hundreds of resources, they are grouped together, and because the API evolves, the resources are versioned. For these reasons, each resource belongs to a given Group and Version, and each resource is uniquely identified by a Group-Version-Resource, commonly known as GVR. To find the various resources in the Kubernetes API, you can browse the OpenAPI specification to extract the distinct paths. Legacy resources (e.g., pods or nodes) will have been introduced early in the Kubernetes API and all belong to the group core and the version v1. The paths to manage legacy resources cluster-wide follow the format /api/ v1/<plural_resource_name>—for example, /api/v1/nodes to manage nodes. Note that the core group is not represented in the path. To manage resources in a given namespace, the path format is /api/v1/namespaces/<namespace_name>/<plural_ resource_name>—for example, /api/v1/namespaces/default/pods to manage pods in the default namespace. Newer resources are accessible through paths following the format /apis/<group>/<version>/<plural_resource_name> or /apis/<group>/<version>/ namespaces/<namespace_name>/<plural_resource_name>. To summarize, the formats of the various paths to access resources are: • /api/v1/<plural_name> – to access legacy non-namespaced resources Ex: /api/v1/nodes to access non-namespaced nodes resources or To access legacy namespaced resources cluster-wide Ex: /api/v1/pods to access pods across all namespaces • /api/v1/namespaces/<ns>/<plural_name> – to access legacy namespaced resources in a specific namespace Ex: /api/v1/namespaces/default/pods to access pods in the default namespace • /apis/<group>/<version>/<plural_name> – to access non- namespaced resources in specific group and version Ex: /apis/storage.k8s.io/v1/storageclasses to access non- namespaced storageclasses (group storage.k8s.io, version v1) Chapter 1 Kubernetes apI IntroduCtIon 8 or To access namespaced resources cluster-wide Ex: /apis/apps/v1/deployments to access deployments across all namespaces • /apis/<group>/<version>/namespaces/<ns>/<plural_name> – to access namespaced resources in a specific namespace Ex: /apis/apps/v1/namespaces/default/deployments to access deployments (group apps, version v1) in the default namespace Sub-resources Following the REST API convention, the resources can have sub-resources. A sub- resource is a resource that belongs to another and can be accessed by specifying its name after the name of the resource, as follows: • /api/v1/<plural>/<res-name>/<sub-resource> Ex: /api/v1/nodes/node1/status • /api/v1/namespaces/<ns>/<plural>/<res-name>/<sub-resource> Ex: /api/v1/namespaces/ns1/pods/pod1/status • /apis/<group>/<version>/<plural>/<res-name>/<sub-resource> Ex: /apis/storage.k8s.io/v1/volumeattachments/volatt1/status • /apis/<grp>/<v>/namespaces/<ns>/<plural>/<name>/<sub-res> Ex: /apis/apps/v1/namespaces/ns1/deployments/dep1/status Most Kubernetes resources have a status sub-resource. You can see, when writing operators, that the operator needs to update the status sub-resource to be able to indicate the state of this resource observed by the operator. The operations that can be executed in the status sub-resource are get, patch, and update. The Pod has more sub-resources, including attach, binding, eviction, exec, log, portforward, and proxy. These sub-resources are useful for getting information about a specific running pod, or executing some specific operation on a running pod, and so on. Chapter 1 Kubernetes apI IntroduCtIon 9 The resources that can Scale (i.e., deployments, replicasets, etc.) have a scale sub- resource. The operations that can be executed in the scale sub-resource are get, patch, and update. Official API Reference Documentation The official reference documentation of the API can be found at https://kubernetes. io/docs/reference/kubernetes-api/. The resources managed by the API are first grouped together by category (i.e., workloads, storage, etc.), and for each category, you can obtain a list of resource names with a short description (Figure 1-3). Figure 1-3. The Kubernetes resources grouped by category Note that these categories are not part of the Kubernetes API definition but are used in this website to help inexperienced users find their way into the multitude of available resources. Chapter 1 Kubernetes apI IntroduCtIon 10 To be precise, the name displayed is not the resource name in the REST sense, but the associated principal kind, as shown in Figure 1-4. For example, when managing Pods, the resource name used in the REST paths is pods (i.e., lowercase and plural), and the definition used to exchange information about Pods during HTTP requests is named Pod (i.e., uppercase and singular). Note that other kinds can be associated with the same resource. In the example in this chapter, the PodList kind (used to exchange information about Lists of Pods) also exists. Figure 1-4. The resources for a specific category, with a short description The Deployment Documentation Let’s explore the reference page for the Deployment available at this address: https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/ deployment-v1/. The title of the page, Deployment, is the principal kind associated with the deployments resource shown in Figure 1-5. Chapter 1 Kubernetes apI IntroduCtIon 12 Figure 1-6. Table of contents for the Deployment documentation page For example, the Deployment kind contains a spec field, of type DeploymentSpec, which is described later. Note that DeploymentSpec is not a structure directly exchanged during HTTP requests, and for that, it is not a kind and does not contain kind or apiVersion fields. Following the principal kind, and its associated definitions, other kinds associated with the resource are displayed. In this case, the DeploymentList kind. Operations Documentation The next subject in the API Documentation for a resource is the list of possible operations on this resource or its sub-resources, also accessible from the table of contents page (see Figure 1-6). By examining the details for the create operation to Create a Deployment, as shown in Figure 1-7, you can see the HTTP Request verb and path to use, the parameters to pass during the request, and the possible responses. The HTTP verb to use for the request is POST and the path is /apis/apps/v1/namespaces/ {namespace}/deployments. Chapter 1 Kubernetes apI IntroduCtIon 

چکیده فارسی

6 افعال API Kubernetes مستقیماً به عملیات در مشخصات OpenAPI نگاشت می شوند. افعال تعریف شده عبارتند از get, create, update, patch, delete, list, watch و deletecollection. مطابقت با افعال HTTP را می توان در جدول 1-1 یافت. جدول 1-1. مکاتبات بین افعال API Kubernetes و افعال HTTP Kubernetes API فعل HTTP دریافت دریافت ایجاد پست به روز رسانی قرار دادن پچ پچ حذف لیست حذف دریافت ساعت دریافت حذف مجموعه حذف حذف انواع Kubernetes زیرمجموعه ای از تعاریف در مشخصات OpenAPI هستند. هنگامی که درخواست ها به API Kubernetes ارسال می شود، ساختارهای داده از طریق بدنه درخواست ها و پاسخ ها مبادله می شوند. این ساختارها دارای فیلدهای مشترک، apiVersion و kind هستند تا به شرکت کنندگان درخواست کمک کنند تا این ساختارها را بشناسند. اگر می‌خواهید User API خود را مدیریت این مفهوم Kind کنید، ساختار User شامل دو فیلد اضافی است، apiVersion و kind - برای مثال، با مقادیر v1 و User. برای تعیین اینکه آیا یک تعریف در مشخصات OpenAPI Kubernetes یک نوع Kubernetes است یا خیر، می توانید به قسمت x-kubernetes-group-version-kind تعریف نگاه کنید. اگر این فیلد تعریف شده باشد، تعریف یک نوع است و مقادیر فیلدهای apiVersion و kind را به شما می دهد. Group-Version-Resource API Kubernetes یک API REST است و در نتیجه منابع را مدیریت می کند و مسیرهای مدیریت این منابع از قراردادهای نامگذاری REST پیروی می کند - یعنی با استفاده از یک نام جمع برای شناسایی یک منبع و توسط گروه بندی این منابع فصل 1 Kubernetes apI مقدمه 7 از آنجایی که Kubernetes API صدها منبع را مدیریت می کند، آنها با هم گروه بندی می شوند و چون API تکامل می یابد، منابع نسخه بندی می شوند. به این دلایل، هر منبع متعلق به یک گروه و نسخه معین است، و هر منبع به طور منحصر به فرد توسط یک Group-Version-Resource، که معمولا به عنوان GVR شناخته می شود، شناسایی می شود. برای یافتن منابع مختلف در Kubernetes API، می‌توانید مشخصات OpenAPI را مرور کنید تا مسیرهای متمایز را استخراج کنید. منابع قدیمی (به عنوان مثال، پادها یا گره ها) در اوایل API Kubernetes معرفی شده اند و همه به هسته گروه و نسخه v1 تعلق دارند. مسیرهای مدیریت منابع قدیمی در کل خوشه از فرمت /api/ v1/ پیروی می کنند—به عنوان مثال، /api/v1/nodes برای مدیریت گره ها. توجه داشته باشید که گروه اصلی در مسیر نمایش داده نمی شود. برای مدیریت منابع در یک فضای نام معین، قالب مسیر /api/v1/namespaces// است—به عنوان مثال، /api/v1/namespaces/default/pods برای مدیریت پادها در فضای نام پیش‌فرض. منابع جدیدتر از طریق مسیرهایی با فرمت /apis/// یا /apis/// namespace// قابل دسترسی هستند. به طور خلاصه، فرمت‌های مسیرهای مختلف برای دسترسی به منابع عبارتند از: • /api/v1/ – برای دسترسی به منابع قدیمی بدون فضای نام به عنوان مثال: /api/v1/nodes برای دسترسی به منابع گره‌های بدون فضای نام یا برای دسترسی به میراث منابع فضای نامی در سراسر خوشه مثال: /api/v1/pods برای دسترسی به پادها در همه فضاهای نام • /api/v1/namespaces// – برای دسترسی به منابع فضای نام قدیمی در یک فضای نام خاص، مثال: /api/v1 /namespaces/default/pods برای دسترسی به پادها در فضای نام پیش‌فرض • /apis/// – برای دسترسی به منابع غیرفاصله نام در گروه و نسخه خاص مانند: /apis/storage.k8s.io /v1/storageclasses برای دسترسی به کلاس‌های ذخیره‌سازی بدون فضای نام (group storage.k8s.io، نسخه v1) فصل 1 Kubernetes apI مقدمه 8 یا برای دسترسی به منابع فضای نام در کل خوشه مثال: /apis/apps/v1/deployments برای دسترسی به استقرار در همه فضاهای نام • /apis///namespaces// - برای دسترسی به منابع فضای نامی در یک فضای نام خاص به عنوان مثال: /apis/apps/v1/namespaces/default/deployments برای دسترسی به استقرارها (گروه برنامه‌ها، نسخه v1) در فضای نام پیش‌فرض منابع فرعی به دنبال قرارداد REST API، منابع می‌توانند منابع فرعی داشته باشند. یک منبع فرعی منبعی است که به دیگری تعلق دارد و می توان با تعیین نام آن پس از نام منبع به صورت زیر به آن دسترسی داشت: • /api/v1/// مثال: /api/v1/nodes/node1/status • /api/v1/namespaces//// مثال: /api/v1/namespaces/ns1/ pods/pod1/status • /apis///// مثال: /apis/storage.k8s.io/v1/volumeattachments/volatt1/status • /apis///namespaces//<جمع>// مثال: /apis/apps/v1/namespaces/ns1/deployments/dep1/status Most منابع Kubernetes دارای یک منبع فرعی وضعیت هستند. هنگام نوشتن عملگرها می بینید که اپراتور باید زیر منبع وضعیت را به روز کند تا بتواند وضعیت این منبع مشاهده شده توسط اپراتور را نشان دهد. عملیاتی که می توان در زیر منبع وضعیت اجرا کرد عبارتند از دریافت، وصله و به روز رسانی. Pod دارای منابع فرعی بیشتری است، از جمله پیوست، اتصال، خروج، exec، log، portforward و proxy. این منابع فرعی برای به دست آوردن اطلاعات در مورد یک غلاف در حال اجرا خاص، یا اجرای برخی عملیات خاص در یک غلاف در حال اجرا و غیره مفید هستند. فصل 1 Kubernetes apI مقدمه 9 منابعی که می توانند Scale کنند (به عنوان مثال، استقرارها، مجموعه های تکراری و غیره) دارای یک منبع فرعی مقیاس هستند. عملیاتی که می توان در زیر منبع مقیاس اجرا کرد عبارتند از دریافت، وصله و به روز رسانی. مستندات مرجع رسمی API اسناد مرجع رسمی API را می توان در https://kubernetes پیدا کرد. io/docs/reference/kubernetes-api/. منابع مدیریت شده توسط API ابتدا بر اساس دسته بندی (به عنوان مثال، حجم کاری، فضای ذخیره سازی، و غیره) با هم گروه بندی می شوند، و برای هر دسته، می توانید لیستی از نام منابع را با توضیح کوتاه به دست آورید (شکل 1-3). شکل 1-3. منابع Kubernetes بر اساس دسته بندی گروه بندی شده اند توجه داشته باشید که این دسته ها بخشی از تعریف Kubernetes API نیستند، اما در این وب سایت برای کمک به کاربران بی تجربه استفاده می شوند تا به منابع متعدد موجود راه پیدا کنند. فصل 1 Kubernetes apI مقدمه 10 به طور دقیق، نام نمایش داده شده نام منبع به معنای REST نیست، بلکه نوع اصلی مرتبط است، همانطور که در شکل 1-4 نشان داده شده است. به عنوان مثال، هنگام مدیریت Pods، نام منبع مورد استفاده در مسیرهای REST، pods است (یعنی حروف کوچک و جمع)، و تعریفی که برای تبادل اطلاعات در مورد Pods در طول درخواست‌های HTTP استفاده می‌شود، Pod نامیده می‌شود (یعنی حروف بزرگ و مفرد). توجه داشته باشید که انواع دیگر را می توان با همان منبع مرتبط کرد. در مثال این فصل، نوع PodList (که برای تبادل اطلاعات در مورد Lists of Pods استفاده می شود) نیز وجود دارد. شکل 1-4. منابع برای یک دسته خاص، با توضیح کوتاه The Deployment Documentation بیایید صفحه مرجع برای استقرار موجود در این آدرس را بررسی کنیم: https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/ deployment-v1 /. عنوان صفحه، Deployment، نوع اصلی مرتبط با منبع استقرار است که در شکل 1-5 نشان داده شده است. فصل 1 Kubernetes apI مقدمه 12 شکل 1-6. فهرست محتویات صفحه مستندات Deployment به عنوان مثال، نوع Deployment حاوی یک فیلد مشخصات از نوع DeploymentSpec است که در ادامه توضیح داده می شود. توجه داشته باشید که DeploymentSpec ساختاری نیست که مستقیماً در طول درخواست‌های HTTP رد و بدل شود و برای آن، یک نوع نیست و حاوی فیلدهای kind یا apiVersion نیست. به دنبال نوع اصلی و تعاریف مرتبط با آن، انواع دیگر مرتبط با منبع نمایش داده می شود. در این مورد، نوع DeploymentList. مستندات عملیات موضوع بعدی در مستندات API برای یک منبع، لیستی از عملیات ممکن در این منبع یا منابع فرعی آن است که از صفحه فهرست مطالب نیز قابل دسترسی است (شکل 1-6 را ببینید). با بررسی جزئیات عملیات ایجاد برای ایجاد استقرار، همانطور که در شکل 1-7 نشان داده شده است، می توانید فعل HTTP Request و مسیر استفاده، پارامترهایی که در طول درخواست ارسال می شوند و پاسخ های احتمالی را مشاهده کنید. فعل HTTP که برای درخواست استفاده می شود POST و مسیر /apis/apps/v1/namespace/ {namespace}/deployments است. فصل اول Kubernetes apI مقدمه