Download Full Version ebookmass - Visit ebookmass.

com

Kubernetes Programming with Go: Programming

Kubernetes Clients and Operators Using Go and the
Kubernetes API 1st Edition Philippe Martin

https://ebookmass.com/product/kubernetes-programming-with-
go-programming-kubernetes-clients-and-operators-using-go-
and-the-kubernetes-api-1st-edition-philippe-martin-2/

OR CLICK HERE

DOWLOAD NOW

Discover More Ebook - Explore Now at ebookmass.com

 Instant digital products (PDF, ePub, MOBI) ready for you
Download now and discover formats that fit your needs...

Kubernetes Programming with Go: Programming Kubernetes

Clients and Operators Using Go and the Kubernetes API 1st
Edition Philippe Martin
https://ebookmass.com/product/kubernetes-programming-with-go-
programming-kubernetes-clients-and-operators-using-go-and-the-
kubernetes-api-1st-edition-philippe-martin-2/
ebookmass.com

Ansible for Kubernetes by Example: Automate Your

Kubernetes Cluster with Ansible 1st Edition Luca Berton

https://ebookmass.com/product/ansible-for-kubernetes-by-example-
automate-your-kubernetes-cluster-with-ansible-1st-edition-luca-
berton-2/
ebookmass.com

Ansible for Kubernetes by Example: Automate Your

Kubernetes Cluster with Ansible 1st Edition Luca Berton

https://ebookmass.com/product/ansible-for-kubernetes-by-example-
automate-your-kubernetes-cluster-with-ansible-1st-edition-luca-berton/

ebookmass.com

Dearly & Homeless Horace (Dearly and The Departed Book 4)

MM L.A. Kaye

https://ebookmass.com/product/dearly-homeless-horace-dearly-and-the-
departed-book-4-mm-l-a-kaye/

ebookmass.com
Red River Deep Carolyn Brown

https://ebookmass.com/product/red-river-deep-carolyn-brown-3/

ebookmass.com

5 Steps to a 5: AP Physics C 2023 (5 Steps to a 5) Greg

Jacobs

https://ebookmass.com/product/5-steps-to-a-5-ap-
physics-c-2023-5-steps-to-a-5-greg-jacobs/

ebookmass.com

Questions of Syntax Richard S. Kayne

https://ebookmass.com/product/questions-of-syntax-richard-s-kayne/

ebookmass.com

His Convenient Match (Lost Fortunes, Found Love Book 6)

Rose Pearson

https://ebookmass.com/product/his-convenient-match-lost-fortunes-
found-love-book-6-rose-pearson/

ebookmass.com

Five Little Pumpkins on Sesame Street Sesame Workshop

https://ebookmass.com/product/five-little-pumpkins-on-sesame-street-
sesame-workshop/

ebookmass.com
Follow Up and Close the Sale Jeff Shore [Shore

https://ebookmass.com/product/follow-up-and-close-the-sale-jeff-shore-
shore/

ebookmass.com
Philippe Martin

Kubernetes Programming with Go

Programming Kubernetes Clients and Operators
Using Go and the Kubernetes API
Philippe Martin
Blanquefort, France

ISBN 978-1-4842-9025-5 e-ISBN 978-1-4842-9026-2

https://doi.org/10.1007/978-1-4842-9026-2

© Philippe Martin 2023

This work is subject to copyright. All rights are solely and exclusively
licensed by the Publisher, whether the whole or part of the material is
concerned, specifically the rights of translation, reprinting, reuse of
illustrations, recitation, broadcasting, reproduction on microfilms or in
any other physical way, and transmission or information storage and
retrieval, electronic adaptation, computer software, or by similar or
dissimilar methodology now known or hereafter developed.

The use of general descriptive names, registered names, trademarks,

service marks, etc. in this publication does not imply, even in the
absence of a specific statement, that such names are exempt from the
relevant protective laws and regulations and therefore free for general
use.

The publisher, the authors, and the editors are safe to assume that the
advice and information in this book are believed to be true and accurate
at the date of publication. Neither the publisher nor the authors or the
editors give a warranty, expressed or implied, with respect to the
material contained herein or for any errors or omissions that may have
been made. The publisher remains neutral with regard to jurisdictional
claims in published maps and institutional affiliations.

This Apress imprint is published by the registered company APress

Media, LLC, part of Springer Nature.
The registered company address is: 1 New York Plaza, New York, NY
10004, U.S.A.
To Mélina and Elsa, my constant source of truth
Introduction
Back in 2017, I was working for a company building video streaming
software. At the end of that year, a small team, including me, got
assigned a new job to work on deploying the Video CDN developed by
the company on Kubernetes. We decided to explore the concept of
Custom Resources and Operators to deploy this CDN.
The current Kubernetes release was 1.9, the concept of Custom
Resource Definition had just been released in 1.7, and the sample-
controller repository was the only documentation we knew of to help
build an Operator. The Kubernetes ecosystem, being especially lively,
had tools appearing in the following months, specifically the
Kubebuilder SDK. Thus, our project was launched.
From that moment on, I spent numerous days exploring how to
build Operators and other programs interacting with the Kubernetes
API. But the damage was done: I had started to learn Kubernetes
programming from specific to general, and it took me a long time to
fully understand the innards of the Kubernetes API.
I have written this book in the hope that it can teach new
Kubernetes developers how to program, from general to specific, with
the Kubernetes API in Go.

Chapters at a Glance
The target reader for this book has some experience working with
REST APIs, accessing them either by HTTP or using clients for specific
languages; and has some knowledge of the Kubernetes platform,
essentially as a user—for example, some experience deploying such
APIs or frontend applications with the help of YAML manifests.
Chapter 1 of the book explores the Kubernetes API and how it
implements the principles of REST. It especially focuses on the
Group-Version-Resource organization and the Kind concept
proposed by the API.
Chapter 2 continues by covering the operations proposed by the API
and the details of each operation, using the HTTP protocol.
 Chapters 3 to 5 describe the common and “low-level” Go libraries to
work with the Kubernetes API: the API and API Machinery Libraries.
Chapters 6 and 7 cover the Client-go Library—the high-level library
to work with the Kubernetes API in Go—and how to unit test code
using this library.
At this point in the book, the reader should be comfortable with
building Go applications working with native resources of the
Kubernetes API.
Chapters 8 and 9 introduce the concept of Custom Resources and
how to work with them in Go.
Chapters 10 to 12 cover the implementation of Kubernetes Operators
using the controller-runtime library.
Chapter 13 explores the Kubebuilder SDK, a tool to help develop and
deploy Kubernetes Operators.
By the end of the book, the reader should be able to start building
Kubernetes operators in Go and have a very good understanding of
what happens behind the scenes.
Any source code or other supplementary material referenced by the
author in this book is available to readers on GitHub via the book's
product page, located at https://github.com/Apress/Kubernetes-
Programming-with-Go-by-Philippe-Martin. For more detailed
information, please visit http://www.apress.com/source-code.
Acknowledgments
I would like to thank the whole Anevia “CDN” team who started
working with me on Kubernetes back in 2018: David, Ansou, Hossam,
Yassine, É tienne, Jason, and Michaël. Special thanks to Damien Lucas for
initiating this project and for having trusted us with this challenge.
My discovery of Kubernetes has been much easier and pleasant
thanks to the TGIK channel and its numerous episodes, hosted by Joe
Beda, Kris Nova, and many others. Plus, thanks to all the Kubernetes
community for such a great ecosystem!
Table of Contents
Chapter 1:​Kubernetes API Introduction
Kubernetes Platform at a Glance
OpenAPI Specification
Verbs and Kinds
Group-Version-Resource
Sub-resources
Official API Reference Documentation
The Deployment Documentation
Operations Documentation
The Pod Documentation
One-Page Version of the Documentation
Conclusion
Chapter 2:​Kubernetes API Operations
Examining Requests
Making Requests
Using kubectl as a Proxy
Creating a Resource
Getting Information About a Resource
Getting the List of Resources
Filtering the Result of a List
Deleting a Resource
Deleting a Collection of Resources
Updating a Resource
Managing Conflicts When Updating a Resource
Using a Strategic Merge Patch to Update a Resource
 Applying Resources Server-side
Watching Resources
Filtering During a Watch Session
Watching After Listing Resources
Restarting a watch Request
Allowing Bookmarks to Efficiently Restart a watch Request
Paginating Results
Getting Results in Various Formats
Getting Results as a Table
Using the YAML Format
Using the Protobuf Format
Conclusion
Chapter 3:​Working with API Resources in Go
API Library Sources and Import
Content of a Package
types.​go
register.​go
doc.​go
generated.​pb.​go and generated.​proto
types_​swagger_​doc_​generated.​go
zz_​generated.​deepcopy.​go
Specific Content in core/​v1
ObjectReference
ResourceList
Taint
Toleration
 Well-Known Labels
Writing Kubernetes Resources in Go
Importing the Package
The TypeMeta Fields
The ObjectMeta Fields
Spec and Status
Comparison with Writing YAML Manifests
A Complete Example
Conclusion
Chapter 4:​Using Common Types
Pointers
Getting the Reference of a Value
Dereferencing a Pointer
Comparing Two Referenced Values
Quantities
Parsing a String as Quantity
Using an inf.​Dec as a Quantity
Using a Scaled Integer as a Quantity
Operations on Quantities
IntOrString
Time
Factory Methods
Operations on Time
Conclusion
Chapter 5:​The API Machinery
The Schema Package
 Scheme
Initialization
Mapping
Conversion
Serialization
RESTMapper
Kind to Resource
Resource to Kind
Finding Resources
The DefaultRESTMappe​r Implementation
Conclusion
Chapter 6:​The Client-go Library
Connecting to the Cluster
In-cluster Configuration
Out-of-Cluster Configuration
Getting a Clientset
Using the Clientset
Examining the Requests
Creating a Resource
Getting Information About a Resource
Getting List of Resources
Filtering the Result of a List
Setting LabelSelector Using the Labels Package
Setting Fieldselector Using the Fields Package
Deleting a Resource
Deleting a Collection of Resources
 Updating a Resource
Using a Strategic Merge Patch to Update a Resource
Applying Resources Server-side with Patch
Server-side Apply Using Apply Configurations
Building an ApplyConfigurati​on from Scratch
Building an ApplyConfigurati​on from an Existing Resource
Watching Resources
Errors and Statuses
Definition of the metav1.​Status Structure
Error Returned by Clientset Operations
RESTClient
Building the Request
Executing the Request
Exploiting the Result
Getting Result as a Table
Discovery Client
RESTMapper
PriorityRESTMapp​er
DeferredDiscover​yRESTMapper
Conclusion
Chapter 7:​Testing Applications Using Client-go
Fake Clientset
Checking the Result of the Function
Reacting to Actions
Checking the Actions
Fake REST Client
 FakeDiscovery Client
Stubbing the ServerVersion
Actions
Mocking Resources
Conclusion
Chapter 8:​Extending Kubernetes API with Custom Resources
Definitions
Performing Operations in Go
The CustomResourceDe​finition in Detail
Naming the Resource
Definition of the Resource Versions
Converting Between Versions
Schema of the Resource
Deploying a Custom Resource Definition
Additional Printer Columns
Conclusion
Chapter 9:​Working with Custom Resources
Generating a Clientset
Using deepcopy-gen
Using client-gen
Using the Generated Clientset
Using the Generated fake Clientset
Using the Unstructured Package and Dynamic Client
The Unstructured Type
The UnstructuredList​Type
Converting Between Typed and Unstructured Objects
 The Dynamic Client
Conclusion
Chapter 10:​Writing Operators withthe Controller-Runtime
Library
The Manager
The Controller
Creating a Controller
Watching Resources
A First Example
Using the Controller Builder
A Second Example Using the ControllerBuilde​r
Injecting Manager Resources into the Reconciler
Using the Client
Getting Information About a Resource
Listing Resources
Creating a Resource
Deleting a Resource
Deleting a Collection of Resources
Updating a Resource
Patching a Resource
Updating the Status of a Resource
Patching the Status of a Resource
Logging
Verbosity
Predefined Values
Logger Name
 Getting the Logger from Context
Events
Conclusion
Chapter 11:​Writing the Reconcile Loop
Writing the Reconcile Function
Checking Whether the Resource Exists
Implementing the Reconciled Resource
Simple Implementation Example
Conclusion
Chapter 12:​Testing the Reconcile Loop
The envtest Package
Installing envtest Binaries
Using envtest
Defining a ginkgo Suite
Writing the Tests
Test 1
Test 2
Test 3
Test 4
Conclusion
Chapter 13:​Creating an Operator with Kubebuilder
Installing Kubebuilder
Creating a Project
Adding a Custom Resource to the Project
Building and Deploying Manifests
Running the Manager Locally
 Personalizing the Custom Resource
Editing the Go Structures
Enabling the Status Subresource
Defining Printer Columns
Regenerating the Files
Implementing the Reconcile Function
Adding RBAC Annotations
Deploying the Operator on the Cluster
Creating a New Version of the Resource
Defining a New Version
Implementing Hub and Convertible
Setting Up the webhook
Updating kustomization Files
Using Various Versions
Conclusion
Index
About the Author
Philippe Martin
has been working with Kubernetes for
five years, first by creating an Operator
to deploy video CDNs into the cloud,
later helping companies deploy their
applications into Kubernetes, then
writing a Client to help developers work
in a Kubernetes environment. Philippe
has passed the CKAD, CKA, and CKS
certifications. He has extensive
experience with distributed systems and
open-source software: he started his
career 20 years ago creating thin clients
based on the Linux kernel and open-
source components. He is currently
working at Red Hat on the Development
Tools team.
Philippe has been active in the development of Kubernetes,
especially its documentation, and participates in the translation of the
official documentation into French, has edited two reference books
about the Kubernetes API and kubectl, and is responsible for the
French translation of the Kubernetes Dashboard. He participated in
Google Season of Docs to create the new Kubernetes API Reference
section of the official documentation and is maintaining it.
About the Technical Reviewers
Bartosz Majsak
writes code for fun and profit while
proudly wearing a red fedora (also
known as the Red Hat). He has been
long-time open-source contributor and
Java developer turned into Golang
aficionado. Bartosz is overly enthusiastic
about coffee, open source, and speaking
at conferences, not necessarily in that
order. One thing that perhaps proves he
is not a total geek is his addiction to
alpine skiing (and running).

Prasanth
is a Blockchain Certified Professional,
Professional Scrum Master, and
Microsoft Certified Trainer who is
passionate about helping others learn
how to use and gain benefits from the
latest technologies. He is a thought
leader and practitioner in Blockchain,
Cloud, and Scrum. He also handles the
Agile Methodology, Cloud, and
Blockchain technology community
initiatives within TransUnion through
coaching, mentoring, and grooming
techniques.
Prasanth is an adjunct professor and
a technical speaker. He was selected as a speaker at the China
International Industry Big Data Expo 2018 by the Chinese government
and also was invited to the International Blockchain Council by the
Government of Telangana and Goa. In addition, he received accolades
from the Chinese government for his presentation at China
International Industry Big Data Expo 2018. Prasanth has published his
Patent, entitled “Digital Educational Certificate Management System
Using IPFS-Based Blockchain.”
To date, he has interacted extensively, reaching more than 50,000
students, mostly within the technical domain. Prasanth is a working
group member of the CryptoCurrency Certification Consortium, the
Scrum Alliance, the Scrum Organization, and the International Institute
of Business Analysis.
© The Author(s), under exclusive license to APress Media, LLC, part of Springer
Nature 2023
P. Martin, Kubernetes Programming with Go
https://doi.org/10.1007/978-1-4842-9026-2_1

1. Kubernetes API Introduction

Philippe Martin1

(1) Blanquefort, France

Kubernetes is a platform to orchestrate containers operating in the

declarative mode. There are one-thousand-and-one ways to describe
how the Kubernetes platform is constructed. This book focuses on
programming with the platform.
The entry point of the Kubernetes platform is the API. This chapter
explores the Kubernetes architecture by highlighting the central role of
the Kubernetes API. It then focuses on the HTTP REST nature of the
Kubernetes API, and on the extensions added to organize the many
resources managed by it.
Finally, you will learn how to navigate the reference documentation
effectively to be able to extract the maximum quantity of useful
information daily.

Kubernetes Platform at a Glance

On one side of the chain, the user declares the high-level resources to
build applications to deploy: Deployments, Ingresses, and so on.
In the middle, controllers are activated to transform these resources
into low-level resources (Pods), and the scheduler distributes these
resources into nodes. On the other side of the chain, the node agents
deploy the low-level resources onto nodes.
The main elements of the Kubernetes platform (commonly called
the control-plane) are highlighted in Figure 1-1 and described in the
following:
1. The API server – this is the central point on the control-plane; the
user and the various pieces of the control-plane contact this API to
create, get, delete, update, and watch resources.

2. The etcd database – this is only accessible by the API Server, is used
to persist the data relative to resources.

3. The Controller manager – this runs the controllers that transform

high-level resources declared by the user into low-level resources
to be deployed on nodes. The controllers are connected to the API
Server, watching for high-level resources and creating, deleting, and
updating low-level resources to satisfy the specifications declared
in high-level resources.

4. Scheduler – this distributes the low-level resources on the various

nodes. The Scheduler is connected to the API Server to watch for
unaffected resources and connect them to nodes.

5. Kubelet – this is an agent running on all nodes of the cluster, and

each agent manages the workloads affected to its node. The kubelet
is connected to the API Server to watch for Pods resources affected
to its node and to deploy the associated containers using the local
container runtime.

6. Kube proxy – this is an agent running on all nodes of the cluster,

and each agent manages the network configurations affected to its
node. The kube proxy is connected to the API Server to watch for
Service resources and to configure associated network rules on its
node.
Figure 1-1 The architecture of Kubernetes

OpenAPI Specification
The Kubernetes API is an HTTP REST API. The Kubernetes team
provides a specification for this API in the OpenAPI format, either in v2
format at
https://github.com/kubernetes/kubernetes/tree/mast
er/api/openapi-spec or in Kubernetes v1.24, in v3 format, at
https://github.com/kubernetes/kubernetes/tree/mast
er/api/openapi-spec/v3.
These specifications also are accessible from the API Server at these
paths: /openapi/v2 and /openapi/v3.
An OpenAPI specification is made up of various parts and, among
these, are a list of paths and a list of definitions. The paths are the URLs
you use to request this API, and for each path, the specification gives
the distinct operations such as get, delete, or post. Then for each
operation, the specification indicates what are the parameters and body
format for the request, and what are the possible response codes and
associated body format for the response.
The parameters and bodies for requests and responses can be
either simple types or, more generally, structures containing data. The
list of definitions includes data structures that help build the
parameters and bodies for the operations’ requests and responses.
Figure 1-2 is a simplified view of a specification for a User API. This
API can accept two different paths: /user/{userId} and /user. The first
path, /user/{userId}, can accept two operations, get and delete,
respectively, to receive information about a specific user, given its user
ID; and to delete information about a specific user, given its user ID. The
second path, /user, can accept a single operation, post, to add a new
user, given its information.
In this API, a definition of a structure User is given, describing the
information for a user: its ID, first name, and last name. This data
structure is used in the response body of the get operation on the first
path, and in the request body of the post operation on the second path.
Figure 1-2 A simplified user API specification

Verbs and Kinds

The Kubernetes API adds two concepts to this specification: the
Kubernetes API Verbs and the Kubernetes Kinds.
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.
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_nam
e>—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>/<plu
ral_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)
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.
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).
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.

Figure 1-3 The Kubernetes resources grouped by category

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.
Figure 1-5 The Deployment documentation page
The apiVersion indicated in the header can help you write a YAML
manifest for a Deployment resource because you need to specify, for
each resource in a Kubernetes manifest, the apiVersion and kind.
In this case, you know the manifest for a deployment will start with
the following:

apiVersion: apps/v1
kind: Deployment

The next header line indicates the import to use when writing Go
code. In Chapter 3, you will see how to use this import when describing
resources in Go.

After the header, a list of structure definitions is described, also

accessible from the table of contents for the Deployment
documentation page in Figure 1-6. The first one is the principal kind of
the resource, optionally followed by structure definitions that are used
in fields of the first kind.

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.
Figure 1-7 Details for a “create” Deployment operation
The {namespace} part of the path indicates a path parameter,
which is to be replaced by the name of the namespace on which you
want to create the deployment. You can specify the query parameters:
dryRun, fieldManager, fieldValidation, and pretty. These parameters
will follow the path with the format path?dryRun=All.
The body of the request must be a Deployment kind. When using
kubectl, you are writing Kubernetes Manifests that contain this body. In
Chapter 3, you will see how to build the body in Go. The possible HTTP
codes for the responses are: 200, 201, 202, and 401; and for the 2xx
codes, the response body will contain a Deployment kind.

The Pod Documentation

Some structures contain many fields. For them, the Kubernetes API
documentation categorizes the fields. An example is the documentation
of the Pod resource.
The documentation page for the Pod resource first contains the
description for the principal kind, Pod, followed by the description of
the PodSpec structure. The PodSpec structure contains about 40
fields. To help you understand the relationships between these fields
and to simplify their exploration, they are arranged into categories. The
PodSpec fields’ categories are the following: Containers, Volumes,
Scheduling, Lifecycle, and so on.
Additionally, for fields containing nested fields, descriptions of them
are generally displayed inline to avoid a back and forth between
structure descriptions. For complex structures, however, the
description is reported subsequently on the page, and a link is present
next to the field name to be able to access it easily.
This is always the case for the Spec and Status structures because
they are very commonly found in almost all the resources. In addition,
this is the case for some structures used in the Pod kind—for example,
Container, EphemeralContainer, LifecycleHandler, NodeAffinity,
and so on.
Some structures used in several resources are placed in the
Common Definitions section, and a link is present next to the field name
to access it easily. In Figure 1-8, you can see the Containers category
inside the description of the PodSpec structure.
Figure 1-8 Extract of the PodSpec structure documentation
You also can see that the fields, containers and initContainers, are
of the same type as Container, which is described later on the page and
is accessible with a link. The imagePullSecrets field is of type
LocalObjectReference, which is described in the Common Definitions
section and also is accessible through a link.

One-Page Version of the Documentation

Another version of the API Reference documentation exists and is
presented on a single page. This version covers all the versions of the
resources served by a Kubernretes version (not just the latest one).
This version (if you want, change the last part of the path to navigate to
another Kubernetes version) can be found at the following URL:
 https://kubernetes.io/docs/reference/generated/k
ubernetes-api/v1.24/

Conclusion
In this chapter, you have been able to discover the architecture of the
Kubernetes platform, and that the API Server plays a central role. The
Kubernetes API is an HTTP REST API, and the resources are categorized
into various versioned groups.
Kinds are specific structures used to exchange data between the API
server and the clients. You can browse, using the official Kubernetes
website, the API specifications in a human-readable form to discover
the structure of the various resources and kinds, the different
operations available for each resource and sub-resource, and their
associated verbs.
© The Author(s), under exclusive license to APress Media, LLC, part of Springer Nature 2023
P. Martin, Kubernetes Programming with Go
https://doi.org/10.1007/978-1-4842-9026-2_2

2. Kubernetes API Operations

Philippe Martin1

(1) Blanquefort, France

The previous chapter described that the Kubernetes API follows REST principles and
enables users to manipulate resources.
In this chapter, you will learn how to perform various operations by making HTTP
requests directly. During your daily work, you probably will not have to interact
directly with the HTTP layer, but it is important to understand how the API works at
this level so that you can understand how to use more easily it with a higher-level
library.

Examining Requests
Before starting to write your own HTTP requests, you can examine with kubectl
which requests are used when executing kubectl commands. This can be achieved by
using the verbose flag, -v, with a value greater than or equal to 6. Table 2-1 shows
which information is displayed at each level.
For example, if you want to know the URL that is called when getting pods for all
namespaces, you can use the following command:

$ kubectl get pods --all-namespaces -v6

loader.go:372] Config loaded from
file: /home/user/.kube/config
round_trippers.go:553] GET
https://192.168.1.194:6443/api/v1/pods?limit=500 200 OK in
745 milliseconds

In the output of the command, you can see that the path used is /api/v1/pods.
Or, when getting pods in a specific namespace, you can see that the path used is
/api/v1/namespaces/default/pods:

$ kubectl get pods --namespace default -v6

loader.go:372] Config loaded from
file: /home/user/.kube/config
round_trippers.go:553] GET
https://192.168.1.194:6443/api/v1/namespaces/default/pods?
limit=500 200 OK in 138 milliseconds

Table 2-1 Verbosity Levels

Level Method Request Events Request Response Response Curl Body

and URL timing timing headers status headers cmd length
-v 6 yes yes – – – – – 0
-v 7 yes – – yes yes – – 0
-v 8 yes – – yes yes yes - ≤ 1024
-v 9 yes yes yes – – yes yes ≤ 10240
-v 10 yes yes yes – – yes yes ∞

Making Requests
This section examines all the possible operations you can do with Kubernetes
resources.

Using kubectl as a Proxy

You must be authenticated to make requests to the Kubernetes API of a cluster,
unless your cluster accepts unauthentified requests, which is unlikely.
A way to run authenticated HTTP requests is to use kubectl as a proxy to make it
deal with the authentication. For this, the kubectl proxy command can be used:

$ kubectl proxy
Starting to serve on 127.0.0.1:8001

On a new terminal, you can now run your HTTP requests without any
authentication. Next, a HOST variable to access the proxy is defined:

$ HOST=http://127.0.0.1:8001

Creating a Resource
You can create a new resource by first creating a Kubernetes manifest describing this
resource—for example, to create a Pod, you can write:

$ cat > pod.yaml <<EOF

apiVersion: v1
kind: Pod
metadata:
name: nginx
spec:
 containers:
- image: nginx
name: nginx
EOF
You then need to pass the resource description into the body of a POST request
(note that the -X POST flag can be omitted because the --data-binary flag is being
used). For example, to create a pod resource use:

$ curl $HOST/api/v1/namespaces/project1/pods
-H "Content-Type: application/yaml"
--data-binary @pod.yaml

This is equivalent to running the kubectl command:

$ kubectl create --namespace project1 -f pod.yaml -o json

Note that the namespace is not indicated in the pod.yaml file. If you add it, you
must specify the same namespace in the YAML file and in the path, or you will get an
error—that is, the namespace of the provided object does not match the namespace
sent on the request.

Getting Information About a Resource

You can obtain information about a specific resource using a GET request and
passing its name as a parameter (and its namespace if it is a namespaced resource)
in the path. In this example, you will request the information for the pod named
nginx in the project1 namespace:

$ curl -X GET
$HOST/api/v1/namespaces/project1/pods/nginx

This will return information about the resource in the JSON format, using the
kind associated with this resource as a structure; in this example, it is a Pod kind.
This is equivalent to running the kubectl command:

$ kubectl get pods --namespace project1 nginx -o json

Getting the List of Resources

For namespaced resources, you can get the list of resources either cluster-wide or in
a specific namespace. For non-namespaced resources, you can get the list of
resources. In any case, you will use a GET request.

Cluster-wide
To get the list of resources cluster-wide, for namespaced or non-namespaced
resources; for example, for the pod resource, use the following:
Random documents with unrelated
content Scribd suggests to you:
 TARTALOM.

A fordító előszava 5
Bevezetés. A társadalomtudományok
módszertanának kezdetleges állapota. A munka
tárgya 15
I. Fejezet. Mi a társadalmi tény? 18

A társadalmi tényt nem lehet annak alapján meghatározni, hogy

valamely társadalomban általános. A társadalmi tény
megkülönböztető jellemvonásai: 1. Külső karaktere az egyéni
tudattal szemben. 2. Kényszerítő ereje, amelyet az egyéni tudatra
gyakorol vagy gyakorolni képes. – Ennek a meghatározásnak
alkalmazása az erkölcsi normákra és a társadalmi áramlatokra. A
meghatározás igazolása. Egy másik forma, amely a társadalmi tényt
jellemzi: egyéni megnyilvánulásaitól való függetlensége. – E
jellemvonás alkalmazása az erkölcsre és a társadalmi áramlatokra. –
A társadalmi tény általánossá lesz azért, mert társadalmi, de nem
társadalmi azért, mert általános. Mennyiben függ össze ez a második
meghatározás az elsővel. A társadalmi morfológia tényei minő
kapcsolatban vannak ugyanezzel a meghatározással. – A társadalmi
tény általános formája.

II. Fejezet. A társadalmi tények megfigyelésére

vonatkozó szabályok 34

Alapelv: a társadalmi tényeket mint dolgokat kell tárgyalnunk.

I. Az ideologiai alakulat, amelyen az összes tudományok
átmennek, miközben köznapi és gyakorlati életbe vágó fogalmakat
dolgoznak ki, ahelyett, hogy a dolgokat leírnák és megmagyaráznák.
– Miért kellett ennek az állapotnak a szociológiában tovább tartani,
mint egyéb tudományokban. Comte, Spencer szociológiájából és a
mai nemzetgazdaságtanból vett tények és bizonyítékok arra nézve,
hogy ez a stádium még nem mult el.
Az okok, hogy ezt elkerüljük: 1 A társadalmi tényeket dolgoknak
kell tekintenünk, mert ezek a tudománynak közvetlen adottságai,
míg az eszmék, minthogy azok ezeknek fejlődéséül tekintetnek,
nincsenek közvetlenül adva. 2. A dolgoknak összes tulajdonságai
megvannak bennük.
Ennek a reformnak analóg esetei azzal a reformmal, amelyen
legújabban a lélektan keresztülment. – Okok, melyeknek alapján a
jövőben a szociológia gyors föllendülését remélhetjük.
II. Az előbbi szabályok közvetlen következményei:
1. A tudományból mindennemű hamis fogalmat ki kell küszöbölni.
A misztikus szempont, amely a szabály alkalmazását
megakadályozza.
2. Mód, hogy a kutatás pozitiv tárgyát megállapítsuk: A tények
csoportosítása közös külső tulajdonságaik alapján. – Az így alkotott
fogalom viszonya a közönséges fogalomhoz. – Példák arra nézve,
hogy milyen tévedéseknek vagyunk kitéve, ha ezt a szabályt
elhanyagoljuk vagy hamisan alkalmazzuk: Spencer és az ő elmélete
a házasságról; Garofalo és definiciója a bűntényről. Általános
tévedés, hogy az alsórendű társadalmak erkölcsnélküliek. – A kezdő
definicióba fölvett tulajdonságok külső volta nem akadálya a
tudományos magyarázatnak.
3. E külső jellemvonásoknak a lehető legtárgyilagosabbaknak kell
lenniök. Hogy ezt elérhessük: A társadalmi tényeket azokon az
oldalukon kell megragadnunk, ahol egyéni nyilvánulásaiktól
elkülönítve jelentkeznek.
 III. Fejezet. A normális és pathológikus
megkülönböztetésre vonatkozó szabályok 74

E megkülönböztetés elméleti és gyakorlati haszna.

Ennek tudományosan lehetségesnek kell lennie, azért, hogy a
tudománynak magatartásában irányítóul szolgáljon.
I. A közönségesen alkalmazott kritériumok vizsgálata: A fájdalom
nem elhatározó jellemvonása a betegségnek, mert az egészséges
állapotnak is alkatrésze; az életbenmaradásra való kilátást nem
csökkenti, mert gyakran normális dolgok (öregség, szülés) hozzák
létre, s nem következik közvetlenül a betegségből; ez a kritérium
igen gyakran nem alkalmazható, különösen a
társadalomtudományban.
A betegséget úgy különböztetjük meg az egészségtől, mint a
normálist az abnormálistól. – A specifikus vagy átlagtípus. – Számot
kell vetnünk a korral, annak megállapítására, hogy a tény normális-e
vagy nem.
A kórosnak ez a meghatározása mennyiben vág össze a
betegségnek közkeletű fogalmával. – Az abnormális esetleges;
hogyan van, hogy az abnormális az élőlényt általában alsóbbrendűvé
teszi.
II. Annak haszna, ha e módszer eredményeit igazoljuk,
olyformán, hogy valamely tény normális vagyis általános voltának
okait fölfedjük. – Ez az igazolás szükséges, ha oly tényekről van szó,
amelyek olyan társadalmakban fordulnak elő, amelyeknek
történelme nem fejeződött be. – Hogyan van, hogy ez a bizonyíték
csak kiegészítésül alkalmazható és csak másodsorban. – Szabályok.
III. E szabályok alkalmazása egyes esetekre, különösen a
bűntény kérdésére. – Egy bizonyos kriminálitás létezése miért
normális jelenség. – Példák a tévedésekre, melyekbe akkor esünk,
ha e szabályokat nem követjük. – Sőt így maga a tudomány is
lehetetlenné válik.
 IV. Fejezet. A társadalmi típusok megalkotására
vonatkozó szabályai 109

A normális és abnormális megkülönböztetése magában foglalja a

társadalmi fajok felállítását. – E fajfogalom haszna; közvetítő a
genus homo és a külön társadalmak fogalma között.
I. A monográfiai eljárás nem eszköz ennek a megalkotására. –
Ezen a módon lehetetlen célt érni. – Az ily módon készült
osztályozás haszontalan. – Az alkalmazandó módszer alapelve: a
társadalmakat összetételük foka szerint megkülönböztetni.
II. Az egyszerű társadalom meghatározása: horda. – Példák a
társadalomnak hasonlóval történő egynehány összekapcsolódásai
formájára és az összetett társadalmakéra egymással. – Az így
alkotott fajokban megkülönböztethetünk változatokat, aszerint, hogy
az alkotó szegmentumok összeolvadtak-e vagy nem. – Szabályok.
III. Az elmondottak mennyiben bizonyítják a társadalomfajok
létét. – A faj természetének különbségei az élettanban és a
társadalomtudományban.

V. Fejezet. A társadalmi tények

megmagyarázására vonatkozó szabályok 125

I. A közhasználatban levő magyarázatok teleológikus jellege.

Valamely tény haszna létének még nem magyarázata. – E két kérdés
kettősségét bizonyítják az életbenmaradás tényei, a szerv és a
funkció függetlensége és ama szolgálatok különfélesége, melyeket
egy és ugyanazon intézmény egymásután teljesíteni képes. – A
causæ efficientes kutatásának szükségessége a társadalmi
tényekben. – Ezeknek az okoknak túlságos nagy jelentősége van a
szociológiában, amit bizonyít a legaprólékosabb társadalmi
szokásokban is nyilvánuló általánosság.
A causa efficienst a funkciótól függetlenül kell meghatározni. –
Miért kell az első kutatásnak ezt a másodikat megelőzni. – Ez
utóbbinak haszna.
 II. Az általában használatos kifejtési eljárás pszichológiai jellege.
– Ez az eljárás félreismeri a társadalmi tény természetét, a melyet
tisztán pszichikai tényre a definició által nem lehet visszavezetni. – A
társadalmi tények csak társadalmi tények által magyarázhatók.
Mi módon lehetséges ez, jóllehet a társadalomnak csak az egyéni
öntudat az anyaga. – Az asszociáció tényének jelentősége, amely új
reálitásokat teremt. – A szociológia és a pszichológia elkülönítése
analog a biológiáéval és a fizika-kémiai tudományokéval.
Vajjon ez a tétel alkalmazható-e a társadalmi formáció tényére.
Pozitiv viszony a pszichikai és társadalmi tények között. Az
előbbiek a maghatározatlan anyag, melyet a társadalmi faktor
általakít; példák. Ha a szociológusok közvetlen szerepet
tulajdonítottak neki a társadalmi élet keletkezésében, ez csak azért
érthető, mert az öntudatállapotokat, amelyek csak átalakult
társadalmi tények, tisztán pszichikai ténynek vették.
Egyéb bizonyítékok e tételnek támogatására: 1. A társadalmi
tényeknek az ethnikai tényezőtől való függetlensége, mely az
organikus-pszichikus rendbe tartozik. 2. A társadalmi fejlődést nem
lehet csupán pszichikai tényekből magyarázni.
Szabályok ehhez a kérdéshez. Minthogy e szabályokat nem
méltatták figyelemre, a szociológiai magyarázatoknak túlságosan
általános karaktere van, s ez őket diszkreditálja. Szükségünk van egy
tulajdonképpeni szociológiai képzettségre.
III. A társadalmi morfológia tényeinek primarius jelentősége van
a szociológiai magyarázatokban: a belső miliő az eredete minden
jelentékeny társadalmi folyamatnak. Különösen fontos szerepe van
ebben a miliőben emberi elemének. A társadalmi probléma
mindenekelőtt ama környezet tulajdonságainak feltalálásában áll,
amely a társadalmi jelenségekre hatást gyakorol. A
jellemvonásoknak két fajtája felel meg különösen e feltételnek: A
társadalom térfogata és dinamikus sűrűsége, a szegmentumok
összeolvadásának fokával mérve.
 A belső környezet másodlagos tulajdonságai. Viszonyuk az
általános környezethez és az együttes élet részleteihez.
A társadalmi környezet e fogalmának jelentősége. Ha ezt
elvetjük, a szociológia nem lesz képes több okozati viszonyt
megállapítani, hanem csak az egymásutániság viszonyát, amely előre
való tudományos megállapítást nem tesz lehetővé. Comte-ból és
Spencer-ből vett példák. E fogalom jelentősége a tények
magyarázásában abban áll, hogy a társadalmi szokások gyakorlati
értéke változhatik, anélkül, hogy önkényes berendezésektől függne.
E kérdésnek a társadalmi típusokhoz való viszonya.
Az így felfogott társadalmi élet belső okoktól függ.
IV. Ennek a szociológiai felfogásnak általános karaktere. –
Hobbes szerint a pszichikai és a társadalmi között a kapcsolat
szintétikus és mesterséges. Spencer és a nemzetgazdászok szerint
természetes és analitikus; szerintünk természetes és szintétikus.
Mennyiben egyeztethetők össze e tulajdonságok. Általános
következtetések.

VI. Fejezet. A bizonyító eljárás szabályai 167

I. Az összehasonlító módszer vagy az indirekt kísérlet a

szociológiai kutatás módszere. Comte úgynevezett történelmi
módszerének hiábavalósága. Felelet Mill ellenvetésére az
összehasonlító szociológiai módszert illetőleg. Ennek az alapelvnek
fontossága: ugyanazon hatásnak mindig ugyanazon ok felel meg.
II. Miért legjobb az összehasonlító módszertani eljárás különböző
fajai közül a párhuzamos variációk módszere: 1. Mert az oksági
kapcsolatot belülről ragadja meg; 2. mert lehetségessé teszi jobb és
kritikaibb bizonyítékok alkalmazását. Mert a szociológia, ámbár egy
eljárásra van korlátozva, egyéb tudományokkal szemben nincs
alárendelt helyzetben a variációk folytán, amellyel rendelkezik.
Szükséges, hogy csak a folytonos és kiterjedt változásokat
hasonlítsuk össze és ne az izolált variációkat.
 III. E sorok képzésének különböző módjai. Esetek, ahol a sor
egyes tagjait egyetlen társadalomból lehet venni. Esetek, ahol ezek
különböző, de ugyanazon fajú társadalmaktól vehetők. Esetek, ahol
a különböző fajokat össze kell hasonlítani. Miért ez a
legáltalánosabb. Az összehasonlító szociológia maga a szociológia.
Elővigyázati rendszabályok bizonyos tévedések elkerülésére
összehasonlítás közben.

Befejezés. E módszer általános jellemvonásai: 185

1. Független mindennemű filozófiától (ez a függetlenség magára

a filozófiára hasznos) és gyakorlati tantól. A szociológia viszonya
ezekkel a tanokkal. A pártokon mi módon tud uralkodni.
2. Tárgyilagossága. A társadalmi tények úgy tekintetnek mint
dolgok. Ez az elv mi módon hatja át az egész módszert.
3. Szociológia karaktere: A társadalmi tények úgy
magyaráztatnak meg, hogy specifikus voltukat megőrzik; a
szociológia mint önálló tudomány. Ennek az önállóságnak birtoka a
legfontosabb haladás, amit a szociológia tehet. Az így tárgyalt
szociológia tekintélye nagyobb.
*** END OF THE PROJECT GUTENBERG EBOOK A SZOCIOLÓGIA
MÓDSZERE ***

Updated editions will replace the previous one—the old editions

will be renamed.

Creating the works from print editions not protected by U.S.

copyright law means that no one owns a United States
copyright in these works, so the Foundation (and you!) can copy
and distribute it in the United States without permission and
without paying copyright royalties. Special rules, set forth in the
General Terms of Use part of this license, apply to copying and
distributing Project Gutenberg™ electronic works to protect the
PROJECT GUTENBERG™ concept and trademark. Project
Gutenberg is a registered trademark, and may not be used if
you charge for an eBook, except by following the terms of the
trademark license, including paying royalties for use of the
Project Gutenberg trademark. If you do not charge anything for
copies of this eBook, complying with the trademark license is
very easy. You may use this eBook for nearly any purpose such
as creation of derivative works, reports, performances and
research. Project Gutenberg eBooks may be modified and
printed and given away—you may do practically ANYTHING in
the United States with eBooks not protected by U.S. copyright
law. Redistribution is subject to the trademark license, especially
commercial redistribution.

START: FULL LICENSE

THE FULL PROJECT GUTENBERG LICENSE
 PLEASE READ THIS BEFORE YOU DISTRIBUTE OR USE THIS WORK

To protect the Project Gutenberg™ mission of promoting the

free distribution of electronic works, by using or distributing this
work (or any other work associated in any way with the phrase
“Project Gutenberg”), you agree to comply with all the terms of
the Full Project Gutenberg™ License available with this file or
online at www.gutenberg.org/license.

Section 1. General Terms of Use and

Redistributing Project Gutenberg™
electronic works
1.A. By reading or using any part of this Project Gutenberg™
electronic work, you indicate that you have read, understand,
agree to and accept all the terms of this license and intellectual
property (trademark/copyright) agreement. If you do not agree
to abide by all the terms of this agreement, you must cease
using and return or destroy all copies of Project Gutenberg™
electronic works in your possession. If you paid a fee for
obtaining a copy of or access to a Project Gutenberg™
electronic work and you do not agree to be bound by the terms
of this agreement, you may obtain a refund from the person or
entity to whom you paid the fee as set forth in paragraph 1.E.8.

1.B. “Project Gutenberg” is a registered trademark. It may only

be used on or associated in any way with an electronic work by
people who agree to be bound by the terms of this agreement.
There are a few things that you can do with most Project
Gutenberg™ electronic works even without complying with the
full terms of this agreement. See paragraph 1.C below. There
are a lot of things you can do with Project Gutenberg™
electronic works if you follow the terms of this agreement and
help preserve free future access to Project Gutenberg™
electronic works. See paragraph 1.E below.
1.C. The Project Gutenberg Literary Archive Foundation (“the
Foundation” or PGLAF), owns a compilation copyright in the
collection of Project Gutenberg™ electronic works. Nearly all the
individual works in the collection are in the public domain in the
United States. If an individual work is unprotected by copyright
law in the United States and you are located in the United
States, we do not claim a right to prevent you from copying,
distributing, performing, displaying or creating derivative works
based on the work as long as all references to Project
Gutenberg are removed. Of course, we hope that you will
support the Project Gutenberg™ mission of promoting free
access to electronic works by freely sharing Project Gutenberg™
works in compliance with the terms of this agreement for
keeping the Project Gutenberg™ name associated with the
work. You can easily comply with the terms of this agreement
by keeping this work in the same format with its attached full
Project Gutenberg™ License when you share it without charge
with others.

1.D. The copyright laws of the place where you are located also
govern what you can do with this work. Copyright laws in most
countries are in a constant state of change. If you are outside
the United States, check the laws of your country in addition to
the terms of this agreement before downloading, copying,
displaying, performing, distributing or creating derivative works
based on this work or any other Project Gutenberg™ work. The
Foundation makes no representations concerning the copyright
status of any work in any country other than the United States.

1.E. Unless you have removed all references to Project

Gutenberg:

1.E.1. The following sentence, with active links to, or other

immediate access to, the full Project Gutenberg™ License must
appear prominently whenever any copy of a Project
Gutenberg™ work (any work on which the phrase “Project
Gutenberg” appears, or with which the phrase “Project
Gutenberg” is associated) is accessed, displayed, performed,
viewed, copied or distributed:

This eBook is for the use of anyone anywhere in the United

States and most other parts of the world at no cost and
with almost no restrictions whatsoever. You may copy it,
give it away or re-use it under the terms of the Project
Gutenberg License included with this eBook or online at
www.gutenberg.org. If you are not located in the United
States, you will have to check the laws of the country
where you are located before using this eBook.

1.E.2. If an individual Project Gutenberg™ electronic work is

derived from texts not protected by U.S. copyright law (does not
contain a notice indicating that it is posted with permission of
the copyright holder), the work can be copied and distributed to
anyone in the United States without paying any fees or charges.
If you are redistributing or providing access to a work with the
phrase “Project Gutenberg” associated with or appearing on the
work, you must comply either with the requirements of
paragraphs 1.E.1 through 1.E.7 or obtain permission for the use
of the work and the Project Gutenberg™ trademark as set forth
in paragraphs 1.E.8 or 1.E.9.

1.E.3. If an individual Project Gutenberg™ electronic work is

posted with the permission of the copyright holder, your use and
distribution must comply with both paragraphs 1.E.1 through
1.E.7 and any additional terms imposed by the copyright holder.
Additional terms will be linked to the Project Gutenberg™
License for all works posted with the permission of the copyright
holder found at the beginning of this work.

1.E.4. Do not unlink or detach or remove the full Project

Gutenberg™ License terms from this work, or any files
 containing a part of this work or any other work associated with
Project Gutenberg™.

1.E.5. Do not copy, display, perform, distribute or redistribute

this electronic work, or any part of this electronic work, without
prominently displaying the sentence set forth in paragraph 1.E.1
with active links or immediate access to the full terms of the
Project Gutenberg™ License.

1.E.6. You may convert to and distribute this work in any binary,
compressed, marked up, nonproprietary or proprietary form,
including any word processing or hypertext form. However, if
you provide access to or distribute copies of a Project
Gutenberg™ work in a format other than “Plain Vanilla ASCII” or
other format used in the official version posted on the official
Project Gutenberg™ website (www.gutenberg.org), you must,
at no additional cost, fee or expense to the user, provide a copy,
a means of exporting a copy, or a means of obtaining a copy
upon request, of the work in its original “Plain Vanilla ASCII” or
other form. Any alternate format must include the full Project
Gutenberg™ License as specified in paragraph 1.E.1.

1.E.7. Do not charge a fee for access to, viewing, displaying,

performing, copying or distributing any Project Gutenberg™
works unless you comply with paragraph 1.E.8 or 1.E.9.

1.E.8. You may charge a reasonable fee for copies of or

providing access to or distributing Project Gutenberg™
electronic works provided that:

• You pay a royalty fee of 20% of the gross profits you derive
from the use of Project Gutenberg™ works calculated using the
method you already use to calculate your applicable taxes. The
fee is owed to the owner of the Project Gutenberg™ trademark,
but he has agreed to donate royalties under this paragraph to
the Project Gutenberg Literary Archive Foundation. Royalty
 payments must be paid within 60 days following each date on
which you prepare (or are legally required to prepare) your
periodic tax returns. Royalty payments should be clearly marked
as such and sent to the Project Gutenberg Literary Archive
Foundation at the address specified in Section 4, “Information
about donations to the Project Gutenberg Literary Archive
Foundation.”

• You provide a full refund of any money paid by a user who

notifies you in writing (or by e-mail) within 30 days of receipt
that s/he does not agree to the terms of the full Project
Gutenberg™ License. You must require such a user to return or
destroy all copies of the works possessed in a physical medium
and discontinue all use of and all access to other copies of
Project Gutenberg™ works.

• You provide, in accordance with paragraph 1.F.3, a full refund of

any money paid for a work or a replacement copy, if a defect in
the electronic work is discovered and reported to you within 90
days of receipt of the work.

• You comply with all other terms of this agreement for free
distribution of Project Gutenberg™ works.

1.E.9. If you wish to charge a fee or distribute a Project

Gutenberg™ electronic work or group of works on different
terms than are set forth in this agreement, you must obtain
permission in writing from the Project Gutenberg Literary
Archive Foundation, the manager of the Project Gutenberg™
trademark. Contact the Foundation as set forth in Section 3
below.

1.F.

1.F.1. Project Gutenberg volunteers and employees expend

considerable effort to identify, do copyright research on,
transcribe and proofread works not protected by U.S. copyright
law in creating the Project Gutenberg™ collection. Despite these
efforts, Project Gutenberg™ electronic works, and the medium
on which they may be stored, may contain “Defects,” such as,
but not limited to, incomplete, inaccurate or corrupt data,
transcription errors, a copyright or other intellectual property
infringement, a defective or damaged disk or other medium, a
computer virus, or computer codes that damage or cannot be
read by your equipment.

1.F.2. LIMITED WARRANTY, DISCLAIMER OF DAMAGES - Except

for the “Right of Replacement or Refund” described in
paragraph 1.F.3, the Project Gutenberg Literary Archive
Foundation, the owner of the Project Gutenberg™ trademark,
and any other party distributing a Project Gutenberg™ electronic
work under this agreement, disclaim all liability to you for
damages, costs and expenses, including legal fees. YOU AGREE
THAT YOU HAVE NO REMEDIES FOR NEGLIGENCE, STRICT
LIABILITY, BREACH OF WARRANTY OR BREACH OF CONTRACT
EXCEPT THOSE PROVIDED IN PARAGRAPH 1.F.3. YOU AGREE
THAT THE FOUNDATION, THE TRADEMARK OWNER, AND ANY
DISTRIBUTOR UNDER THIS AGREEMENT WILL NOT BE LIABLE
TO YOU FOR ACTUAL, DIRECT, INDIRECT, CONSEQUENTIAL,
PUNITIVE OR INCIDENTAL DAMAGES EVEN IF YOU GIVE
NOTICE OF THE POSSIBILITY OF SUCH DAMAGE.

1.F.3. LIMITED RIGHT OF REPLACEMENT OR REFUND - If you

discover a defect in this electronic work within 90 days of
receiving it, you can receive a refund of the money (if any) you
paid for it by sending a written explanation to the person you
received the work from. If you received the work on a physical
medium, you must return the medium with your written
explanation. The person or entity that provided you with the
defective work may elect to provide a replacement copy in lieu
of a refund. If you received the work electronically, the person
or entity providing it to you may choose to give you a second
opportunity to receive the work electronically in lieu of a refund.
If the second copy is also defective, you may demand a refund
in writing without further opportunities to fix the problem.

1.F.4. Except for the limited right of replacement or refund set

forth in paragraph 1.F.3, this work is provided to you ‘AS-IS’,
WITH NO OTHER WARRANTIES OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR ANY PURPOSE.

1.F.5. Some states do not allow disclaimers of certain implied

warranties or the exclusion or limitation of certain types of
damages. If any disclaimer or limitation set forth in this
agreement violates the law of the state applicable to this
agreement, the agreement shall be interpreted to make the
maximum disclaimer or limitation permitted by the applicable
state law. The invalidity or unenforceability of any provision of
this agreement shall not void the remaining provisions.

1.F.6. INDEMNITY - You agree to indemnify and hold the

Foundation, the trademark owner, any agent or employee of the
Foundation, anyone providing copies of Project Gutenberg™
electronic works in accordance with this agreement, and any
volunteers associated with the production, promotion and
distribution of Project Gutenberg™ electronic works, harmless
from all liability, costs and expenses, including legal fees, that
arise directly or indirectly from any of the following which you
do or cause to occur: (a) distribution of this or any Project
Gutenberg™ work, (b) alteration, modification, or additions or
deletions to any Project Gutenberg™ work, and (c) any Defect
you cause.

Section 2. Information about the Mission

of Project Gutenberg™
Project Gutenberg™ is synonymous with the free distribution of
electronic works in formats readable by the widest variety of
computers including obsolete, old, middle-aged and new
computers. It exists because of the efforts of hundreds of
volunteers and donations from people in all walks of life.

Volunteers and financial support to provide volunteers with the

assistance they need are critical to reaching Project
Gutenberg™’s goals and ensuring that the Project Gutenberg™
collection will remain freely available for generations to come. In
2001, the Project Gutenberg Literary Archive Foundation was
created to provide a secure and permanent future for Project
Gutenberg™ and future generations. To learn more about the
Project Gutenberg Literary Archive Foundation and how your
efforts and donations can help, see Sections 3 and 4 and the
Foundation information page at www.gutenberg.org.

Section 3. Information about the Project

Gutenberg Literary Archive Foundation
The Project Gutenberg Literary Archive Foundation is a non-
profit 501(c)(3) educational corporation organized under the
laws of the state of Mississippi and granted tax exempt status
by the Internal Revenue Service. The Foundation’s EIN or
federal tax identification number is 64-6221541. Contributions
to the Project Gutenberg Literary Archive Foundation are tax
deductible to the full extent permitted by U.S. federal laws and
your state’s laws.

The Foundation’s business office is located at 809 North 1500

West, Salt Lake City, UT 84116, (801) 596-1887. Email contact
links and up to date contact information can be found at the
Foundation’s website and official page at
www.gutenberg.org/contact
 Section 4. Information about Donations to
the Project Gutenberg Literary Archive
Foundation
Project Gutenberg™ depends upon and cannot survive without
widespread public support and donations to carry out its mission
of increasing the number of public domain and licensed works
that can be freely distributed in machine-readable form
accessible by the widest array of equipment including outdated
equipment. Many small donations ($1 to $5,000) are particularly
important to maintaining tax exempt status with the IRS.

The Foundation is committed to complying with the laws

regulating charities and charitable donations in all 50 states of
the United States. Compliance requirements are not uniform
and it takes a considerable effort, much paperwork and many
fees to meet and keep up with these requirements. We do not
solicit donations in locations where we have not received written
confirmation of compliance. To SEND DONATIONS or determine
the status of compliance for any particular state visit
www.gutenberg.org/donate.

While we cannot and do not solicit contributions from states

where we have not met the solicitation requirements, we know
of no prohibition against accepting unsolicited donations from
donors in such states who approach us with offers to donate.

International donations are gratefully accepted, but we cannot

make any statements concerning tax treatment of donations
received from outside the United States. U.S. laws alone swamp
our small staff.

Please check the Project Gutenberg web pages for current

donation methods and addresses. Donations are accepted in a
number of other ways including checks, online payments and
credit card donations. To donate, please visit:
www.gutenberg.org/donate.

Section 5. General Information About

Project Gutenberg™ electronic works
Professor Michael S. Hart was the originator of the Project
Gutenberg™ concept of a library of electronic works that could
be freely shared with anyone. For forty years, he produced and
distributed Project Gutenberg™ eBooks with only a loose
network of volunteer support.

Project Gutenberg™ eBooks are often created from several

printed editions, all of which are confirmed as not protected by
copyright in the U.S. unless a copyright notice is included. Thus,
we do not necessarily keep eBooks in compliance with any
particular paper edition.

Most people start at our website which has the main PG search
facility: www.gutenberg.org.

This website includes information about Project Gutenberg™,

including how to make donations to the Project Gutenberg
Literary Archive Foundation, how to help produce our new
eBooks, and how to subscribe to our email newsletter to hear
about new eBooks.
Welcome to our website – the ideal destination for book lovers and
knowledge seekers. With a mission to inspire endlessly, we offer a
vast collection of books, ranging from classic literary works to
specialized publications, self-development books, and children's
literature. Each book is a new journey of discovery, expanding
knowledge and enriching the soul of the reade

Our website is not just a platform for buying books, but a bridge
connecting readers to the timeless values of culture and wisdom. With
an elegant, user-friendly interface and an intelligent search system,
we are committed to providing a quick and convenient shopping
experience. Additionally, our special promotions and home delivery
services ensure that you save time and fully enjoy the joy of reading.

Let us accompany you on the journey of exploring knowledge and

personal growth!

ebookmass.com